From e9dec8213a30bb12b4499bea4b8fdac6d55fa9f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update OAM Principles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson. --- system/doc/oam/oam_intro.xml | 391 +++++++++++++++++++++---------------------- 1 file changed, 187 insertions(+), 204 deletions(-) (limited to 'system/doc/oam') 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 @@ A oam_intro.xml -

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. -

-

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. -

-

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. -

+ +

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.

+ +

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.

+ +

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.

Terminology -

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 is sent from a manager to an agent when it accesses management information.to the - agent (server), the agent sends A reply is sent from the agent as a response to a request from a manager.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 A notification is sent spontaneously from an agent to a manager, e.g. an alarm.to the - manager. The picture below illustrates the idea.

+

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:

+ +

Usually a few managers communicate with many agents.

 +

The agent can spontaneously send a notification, for example, + an alarm, to the manager.

 + +

The following picture illustrates the idea:

+ Terminology -

The manager is often referred to as the , to - emphasize that it usually is realized as a program that presents - data to an operator. -

-

The agent is an entity that executes within a . - 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. -

-

The management information is defined in an . - 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 , 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. -

+ +

The manager is often referred to as the Network Management + System (NMS), to emphasize that it usually is realized as a + program that presents data to an operator.

+ +

The agent is an entity that executes within a Network + Element (NE). 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.

+ +

The management information is defined in a Management + Information Base (MIB). 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.

+ +

Usually, the entities defined in the MIB are + called Managed Objects (MOs), 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.

Model -

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. -

-

The different entities involved in this model are the which terminates the management protocol, and the - 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 - instrumentation, and the function that implements it is - called . 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. -

-

When a manager makes a request to the agent, we have the - following picture:

+

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.

+ +

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 instrumentation and the + function that implements it is called instrumentation + function. 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.

+ +

When a manager makes a request to the agent, the following + illustrates the situation:

+ - Request to an agent by a manager + Request to An Agent by a Manager -

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. -

-

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. -

-

For example, a system that is managed with SNMP and HTTP may be - structured in the following way:

+ +

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.

+ +

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.

+ +

For example, a system that is managed with SNMP and HTTP + can be structured as follows:

+ - Structure of a system managed with SNMP and HTTP + Structure of a System Managed with SNMP and HTTP -

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:

+ +

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:

+ - Notification handling + Notification Handling -

The main idea is that the resource sends the notfications as - Erlang terms to a dedicated gen_event 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. -

+ +

The main idea is that the resource sends the notifications as + Erlang terms to a dedicated gen_event 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.

- SNMP based OAM -

For all OAM components, SNMP adaptations are provided. Other - adaptations may be defined in the future. -

+ SNMP-Based OAM +

For all OAM components, SNMP adaptations are provided. Other + adaptations might be defined in the future.

+

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. -

+ 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.

- MIB structure -

The top-level OTP MIB is called OTP-REG, and it is - included in the sasl application. All other OTP mibs - import some objects from this MIB. -

-

Each MIB is contained in one application. The MIB text files - are stored under .mib]]> in the application - directory. The generated .hrl files with constant - declarations are stored under .hrl]]>, and - the compiled MIBs are stored under - .bin]]>. For example, the OTP-MIB - is included in the sasl application: -

+ MIB Structure +

The top-level OTP MIB is called OTP-REG and it is + included in the sasl application. All other OTP MIBs + import some objects from this MIB.

+ +

Each MIB is contained in one application. The MIB text + files are stored under .mib]]> in + the application directory. The generated .hrl files + with constant declarations are stored under + .hrl]]>, and the compiled MIBs + are stored under .bin]]>. + For example, the OTP-MIB is included in the + sasl application:

+ sasl-1.3/mibs/OTP-MIB.mib - include/OTP-MIB.hrl - priv/mibs/OTP-MIB.bin -

An application that needs to IMPORT this mib into another - MIB, should use the il option to the snmp mib compiler: -

+include/OTP-MIB.hrl +priv/mibs/OTP-MIB.bin + +

An application that needs to import this MIB into another + MIB is to use the il option to the SNMP MIB compiler:

+ snmp:c("MY-MIB", [{il, ["sasl/priv/mibs"]}]). +

If the application needs to include the generated - .hrl file, it should use the -include_lib - directive to the Erlang compiler. -

+ .hrl file, it is to use the -include_lib + directive to the Erlang compiler:

+ -module(my_mib). - -include_lib("sasl/include/OTP-MIB.hrl"). -

The following MIBs are defined in the OTP system: -

- - OTP-REG (sasl) - -

This MIB contains the top-level OTP registration - objects, used by all other MIBs. -

- - OTP-TC (sasl) - -

This MIB contains the general Textual Conventions, - which can be used by any other MIB. -

- - OTP-MIB (sasl) - -

This MIB contains objects for instrumentation of the - Erlang nodes, the Erlang machines and the applications in - the system. -

- - OTP-OS-MON-MIB (os_mon) - -

This MIB contains objects for instrumentation of disk, - memory and cpu usage of the nodes in the system. -

- - OTP-SNMPEA-MIB (snmp) - -

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). -

- - OTP-EVA-MIB (eva) - -

This MIB contains objects for instrumentation and - control of the events and alarms in the system. -

- - OTP-LOG-MIB (eva) - -

This MIB contains objects for instrumentation and - control of the logs and FTP transfer of logs. -

- - OTP-EVA-LOG-MIB (eva) - -

This MIB contains objects for instrumentation and - control of the events and alarm logs in the system. -

- - OTP-SNMPEA-LOG-MIB (eva) - -

This MIB contains objects for instrumentation and - control of the snmp audit trail log in the system. -

- - + +

The following MIBs are defined in the OTP system:

+ +

OTP-REG) (in sasl) contains the top-level + OTP registration objects, used by all other MIBs.

 +

OTP-TC (in sasl) contains the general + Textual Conventions, which can be used by any other MIB.

 +

OTP-MIB (in sasl) contains objects for + instrumentation of the Erlang nodes, the Erlang machines, + and the applications in the system.

 +

OTP-OS-MON-MIB (in oc_mon) contains + objects for instrumentation of disk, memory, and CPU use + of the nodes in the system.

 +

OTP-SNMPEA-MIB (in snmp) + 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).

 +

OTP-EVA-MIB (in eva) contains objects + for instrumentation and control of the events and alarms in + the system.

 +

OTP-LOG-MIB (in eva) contains objects + for instrumentation and control of the logs and FTP transfer of + logs.

 +

OTP-EVA-LOG-MIB (in eva) contains objects + for instrumentation and control of the events and alarm logs + in the system.

 +

OTP-SNMPEA-LOG-MIB (in eva) contains + objects for instrumentation and control of the SNMP audit + trail log in the system.

 + +

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 otp_mib:init(Agent) to load the MIB, - and otp_mib:stop(Agent) to unload the MIB. See the - application manual page for each application for a description - of how to load each MIB. -

+ 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 otp_mib:init(Agent) to load the MIB, + and otp_mib:stop(Agent) to unload the MIB. See the + manual page for each application for a description of how + to load each MIB.

-- cgit v1.2.3 From 738c34d4bb8f1a3811acd00af8c6c12107f8315b Mon Sep 17 00:00:00 2001 From: Bruce Yinhe Date: Thu, 18 Jun 2015 11:31:02 +0200 Subject: Change license text to APLv2 --- system/doc/oam/Makefile | 21 +++++++++++---------- system/doc/oam/book.xml | 21 +++++++++++---------- system/doc/oam/oam_intro.xml | 21 +++++++++++---------- system/doc/oam/part.xml | 21 +++++++++++---------- system/doc/oam/xmlfiles.mk | 21 +++++++++++---------- 5 files changed, 55 insertions(+), 50 deletions(-) (limited to 'system/doc/oam') 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 @@ Ericsson AB. 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. diff --git a/system/doc/oam/oam_intro.xml b/system/doc/oam/oam_intro.xml index de4867ca16..22a2080fd9 100644 --- a/system/doc/oam/oam_intro.xml +++ b/system/doc/oam/oam_intro.xml @@ -8,16 +8,17 @@ Ericsson AB. 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. 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 @@ Ericsson AB. 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. 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% # -- cgit v1.2.3