diff --git a/system/doc/README.md b/system/doc/README.md index d5abd3054526..da747483baba 100644 --- a/system/doc/README.md +++ b/system/doc/README.md @@ -21,7 +21,5 @@ to use Erlang/OTP and different aspects of working with Erlang/OTP. The guides a This section informs on interoperability, that is, information exchange, between Erlang and other programming languages. The included examples mainly treat interoperability between Erlang and C. -* [OAM Principles](oam/oam.md) - - How to build Operations & Maintenance support into your Erlang/OTP system. * [Embedded Systems User's Guide](embedded/embedded.md) - This section describes the issues that are specific for running Erlang on an embedded system. diff --git a/system/doc/docs.exs b/system/doc/docs.exs index 32ad02a4a6ad..12691d3d9536 100644 --- a/system/doc/docs.exs +++ b/system/doc/docs.exs @@ -74,8 +74,7 @@ "design_principles/distributed_applications.md": [], "design_principles/release_structure.md": [], "design_principles/release_handling.md": [], - "design_principles/appup_cookbook.md": [], - "oam/oam.md": [] + "design_principles/appup_cookbook.md": [] ], main: "readme", api_reference: false, diff --git a/system/doc/guides b/system/doc/guides index f1fc430eb983..784ff2ba91d3 100644 --- a/system/doc/guides +++ b/system/doc/guides @@ -6,5 +6,4 @@ programming_examples:Programming Examples reference_manual:Erlang Reference Manual efficiency_guide:Efficiency Guide tutorial:Interoperability Tutorial -oam:OAM Principles embedded:Embedded Systems User's Guide diff --git a/system/doc/oam/assets/snmp_model_1.fig b/system/doc/oam/assets/snmp_model_1.fig deleted file mode 100644 index ab5ec76eaf49..000000000000 --- a/system/doc/oam/assets/snmp_model_1.fig +++ /dev/null @@ -1,42 +0,0 @@ -#FIG 3.1 -Portrait -Center -Inches -1200 2 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 3900 2850 5625 2850 5625 3600 3900 3600 3900 2850 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1500 2850 3225 2850 3225 3600 1500 3600 1500 2850 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2775 1500 4575 1500 4575 2325 2775 2325 2775 1500 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 5025 4200 6225 4200 6225 4800 5025 4800 5025 4200 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1650 4200 2850 4200 2850 4800 1650 4800 1650 4200 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 3600 825 3600 1500 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 3150 2325 2325 2850 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 4200 2325 4800 2850 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 2250 3600 2250 4200 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 4500 3600 4050 4200 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 5175 3600 5700 4200 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 6975 1050 6975 4350 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 3450 4200 4650 4200 4650 4800 3450 4800 3450 4200 -4 0 -1 0 0 0 12 0.0000 4 135 1110 1875 3300 Instrumentation\001 -4 0 -1 0 0 0 12 0.0000 4 135 1110 4200 3300 Instrumentation\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 2025 4575 Res1\001 -4 0 -1 0 0 0 12 0.0000 4 135 345 3450 525 NET\001 -4 0 -1 0 0 0 12 0.0000 4 180 435 3375 1950 Agent\001 -4 0 -1 0 0 0 12 0.0000 4 135 330 6825 600 flow\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 3825 4575 Res2\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 5475 4575 Res3\001 -4 0 -1 0 0 0 12 0.0000 4 135 240 1500 2175 NE\001 diff --git a/system/doc/oam/assets/snmp_model_1.gif b/system/doc/oam/assets/snmp_model_1.gif deleted file mode 100644 index cf44d0fcc4f7..000000000000 Binary files a/system/doc/oam/assets/snmp_model_1.gif and /dev/null differ diff --git a/system/doc/oam/assets/snmp_model_2.fig b/system/doc/oam/assets/snmp_model_2.fig deleted file mode 100644 index 7719ea58bf60..000000000000 --- a/system/doc/oam/assets/snmp_model_2.fig +++ /dev/null @@ -1,52 +0,0 @@ -#FIG 3.1 -Landscape -Center -Inches -1200 2 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1200 1200 2475 1200 2475 1800 1200 1800 1200 1200 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2475 1800 2475 1800 2475 1800 2475 1800 2475 1800 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 3600 1200 4875 1200 4875 1800 3600 1800 3600 1200 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 3600 1200 4875 1200 4875 1800 3600 1800 3600 1200 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1050 2400 2550 2400 2550 3000 1050 3000 1050 2400 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 3450 2400 4950 2400 4950 3000 3450 3000 3450 2400 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1200 3600 2400 3600 2400 4125 1200 4125 1200 3600 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2400 4125 2400 4125 2400 4125 2400 4125 2400 4125 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2775 3600 3900 3600 3900 4125 2775 4125 2775 3600 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 4275 3600 5400 3600 5400 4125 4275 4125 4275 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 1800 1800 1800 2400 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 4200 1800 4200 2400 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 1800 3000 1800 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 3 - 4125 3000 3300 3600 3375 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 4350 3000 4875 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 2250 3000 3150 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 3600 3000 2100 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 6225 1200 6225 3600 -4 0 -1 0 0 0 12 0.0000 4 135 510 1500 1425 SNMP\001 -4 0 -1 0 0 0 12 0.0000 4 135 450 3825 1425 HTTP\001 -4 0 -1 0 0 0 12 0.0000 4 135 465 3825 1665 Server\001 -4 0 -1 0 0 0 12 0.0000 4 135 465 1500 1665 Server\001 -4 0 -1 0 0 0 12 0.0000 4 135 1110 1275 2775 Instrumentation\001 -4 0 -1 0 0 0 12 0.0000 4 135 1110 3675 2775 Instrumentation\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 1575 3900 Res1\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 3150 3900 Res2\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 4500 3900 Res3\001 -4 0 -1 0 0 0 12 0.0000 4 135 330 6075 1050 flow\001 diff --git a/system/doc/oam/assets/snmp_model_2.gif b/system/doc/oam/assets/snmp_model_2.gif deleted file mode 100644 index 79c6ef1af571..000000000000 Binary files a/system/doc/oam/assets/snmp_model_2.gif and /dev/null differ diff --git a/system/doc/oam/assets/snmp_model_3.fig b/system/doc/oam/assets/snmp_model_3.fig deleted file mode 100644 index b2356c7cfe7b..000000000000 --- a/system/doc/oam/assets/snmp_model_3.fig +++ /dev/null @@ -1,56 +0,0 @@ -#FIG 3.1 -Landscape -Center -Inches -1200 2 -6 1800 1500 2325 1950 -4 0 -1 0 0 0 12 0.0000 4 135 465 1800 1890 Server\001 -4 0 -1 0 0 0 12 0.0000 4 135 510 1800 1650 SNMP\001 --6 -6 4200 1425 4725 1875 -4 0 -1 0 0 0 12 0.0000 4 135 450 4200 1575 HTTP\001 -4 0 -1 0 0 0 12 0.0000 4 135 465 4200 1815 Server\001 --6 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1200 1200 3000 1200 3000 2250 1200 2250 1200 1200 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 3600 1200 5400 1200 5400 2250 3600 2250 3600 1200 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1200 3000 3000 3000 3000 3825 1200 3825 1200 3000 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 3600 3000 5400 3000 5400 3825 3600 3825 3600 3000 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2475 4500 4200 4500 4200 5400 2475 5400 2475 4500 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 4200 6000 5400 6000 5400 6600 4200 6600 4200 6000 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1200 6000 2400 6000 2400 6600 1200 6600 1200 6000 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2700 6000 3900 6000 3900 6600 2700 6600 2700 6000 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 2100 2250 2100 3000 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 4500 2250 4500 3000 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 2100 3825 3000 4500 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 4500 3825 3600 4500 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 1800 6000 3000 5400 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 3300 6000 3300 5400 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 4800 6000 3600 5400 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 1 2 - 2 1 1.00 60.00 120.00 - 6600 1575 6600 5850 -4 0 -1 0 0 0 12 0.0000 4 135 1110 3900 3450 Instrumentation\001 -4 0 -1 0 0 0 12 0.0000 4 135 1110 1500 3450 Instrumentation\001 -4 0 -1 0 0 0 12 0.0000 4 165 720 3000 4950 gen_event\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 3150 6375 Res2\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 4650 6375 Res3\001 -4 0 -1 0 0 0 12 0.0000 4 135 360 1650 6375 Res1\001 -4 0 -1 0 0 0 12 0.0000 4 135 330 6450 1275 flow\001 diff --git a/system/doc/oam/assets/snmp_model_3.gif b/system/doc/oam/assets/snmp_model_3.gif deleted file mode 100644 index dbc8157ed113..000000000000 Binary files a/system/doc/oam/assets/snmp_model_3.gif and /dev/null differ diff --git a/system/doc/oam/assets/terminology.fig b/system/doc/oam/assets/terminology.fig deleted file mode 100644 index 5a3638764ab8..000000000000 --- a/system/doc/oam/assets/terminology.fig +++ /dev/null @@ -1,37 +0,0 @@ -#FIG 3.1 -Portrait -Center -Inches -1200 2 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2400 525 3600 525 3600 1050 2400 1050 2400 525 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 2400 1950 3600 1950 3600 2475 2400 2475 2400 1950 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 - 1575 3075 2775 3075 2775 3600 1575 3600 1575 3075 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 1 - 3000 2475 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 - 3600 750 3600 825 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 3075 3075 4275 3075 4275 3600 3075 3600 3075 3075 -2 1 1 1 -1 7 0 0 -1 4.000 0 0 7 0 0 2 - 3000 2475 3675 3075 -2 1 1 1 -1 7 0 0 -1 4.000 0 0 7 0 0 2 - 3000 2475 2175 3075 -2 1 1 1 -1 7 0 0 -1 4.000 0 0 7 0 0 2 - 3000 1050 3000 1950 -2 1 1 1 -1 7 0 0 -1 4.000 0 0 7 0 0 2 - 3600 750 4275 1350 -2 1 1 1 -1 7 0 0 -1 4.000 0 0 7 0 0 2 - 3600 2175 4275 1650 -4 0 -1 0 0 0 14 0.0000 4 105 330 3975 2100 sees\001 -4 0 -1 0 0 0 14 0.0000 4 150 450 1275 750 NMS\001 -4 0 -1 0 0 0 14 0.0000 4 150 420 1275 1575 NET\001 -4 0 -1 0 0 0 14 0.0000 4 150 285 1350 2700 NE\001 -4 0 -1 0 0 0 14 0.0000 4 105 330 3975 975 sees\001 -4 0 -1 0 0 0 14 0.0000 4 150 390 4125 1575 MIB\001 -4 0 -1 0 0 0 14 0.0000 4 150 405 1950 3375 Res1\001 -4 0 -1 0 0 0 14 0.0000 4 150 405 3450 3375 Res2\001 -4 0 -1 0 0 0 14 0.0000 4 195 510 2775 2325 Agent\001 -4 0 -1 0 0 0 14 0.0000 4 195 735 2625 825 Manager\001 diff --git a/system/doc/oam/assets/terminology.gif b/system/doc/oam/assets/terminology.gif deleted file mode 100644 index 89f071abf64d..000000000000 Binary files a/system/doc/oam/assets/terminology.gif and /dev/null differ diff --git a/system/doc/oam/oam.md b/system/doc/oam/oam.md deleted file mode 100644 index f9d3d5e7051c..000000000000 --- a/system/doc/oam/oam.md +++ /dev/null @@ -1,182 +0,0 @@ - -# Introduction - -[](){: #oam-principles } - -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 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](assets/terminology.gif "Terminology") - -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 - -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](assets/snmp_model_1.gif "Request to An Agent by a Manager") - -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](assets/snmp_model_2.gif "Structure of a System Managed with SNMP and HTTP") - -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](assets/snmp_model_3.gif "Notification Handling") - -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 might -be defined in the future. - -The OAM components, and some other OTP applications, define 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 SNMP -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 -`mibs/.mib` in the application directory. The generated `.hrl` files with -constant declarations are stored under `include/.hrl`, and the compiled -MIBs are stored under `priv/mibs/.bin`. - -An application that needs to import an MIB into another MIB is to use the `il` -option to the SNMP MIB compiler: - -```erlang -snmp:c("MY-MIB", [{il, ["snmp/priv/mibs"]}]). -``` - -If the application needs to include a generated `.hrl` file, it is to use the -`-include_lib` directive to the Erlang compiler: - -```erlang --module(my_mib). --include_lib("snmp/include/OTP-REG.hrl"). -``` - -Here is a list of some of the MIBs defined in the OTP system: - -- `OTP-REG` (in SNMP) contains the top-level OTP registration objects, used by - all other MIBs. -- `OTP-TC` (in SNMP) contains the general Textual Conventions, which can be used - by any other MIB. -- `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). - -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 `snmpa:load_mibs(Agent, [Mib])` to load the MIB, and -`snmpa:unload_mibs(Agent, [Mib])` to unload the MIB. See the manual page for -each application for a description of how to load each MIB.