From: Claudio D. Gasparini Date: Fri, 21 May 2021 08:57:12 +0000 (+0200) Subject: Document FM / PM Adopter X-Git-Tag: 1.0.0~12 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=463f8d22fb7b67cdbe7df8878ff75df5a186f2b1;p=oam%2Fnf-oam-adopter.git Document FM / PM Adopter Issue-ID: OAM-208 Signed-off-by: Claudio D. Gasparini Change-Id: Ie23caf5671798972a8cffd9f79b529be53154c35 --- diff --git a/docs/deployment-guide.rst b/docs/deployment-guide.rst index 69c1bde..8e17ce0 100644 --- a/docs/deployment-guide.rst +++ b/docs/deployment-guide.rst @@ -5,4 +5,16 @@ Deployment Guide ================ -This document provides a quickstart for deployment of the NF OAM Adopter. \ No newline at end of file +Build + +.. code-block:: bash + + cd ves-nf-oam-adopter + mvn clean install -Pdocker + +Go to solution folder and execute + +.. code-block:: bash + + cd solution + docker-compose up \ No newline at end of file diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index 08153d6..8207a84 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -5,4 +5,7 @@ Developer Guide =============== -This document provides a quickstart for developers of the NF OAM Adopter. \ No newline at end of file +Architecture design of FM / PM Adopter + +.. image:: nf-oam-adopter-diagram.png + :alt: Diagram \ No newline at end of file diff --git a/docs/nf-oam-adopter-diagram.png b/docs/nf-oam-adopter-diagram.png new file mode 100755 index 0000000..8f32f84 Binary files /dev/null and b/docs/nf-oam-adopter-diagram.png differ diff --git a/docs/overview.rst b/docs/overview.rst index 88a0a1f..08c9b4c 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -2,7 +2,29 @@ .. SPDX-License-Identifier: CC-BY-4.0 .. Copyright (C) 2021 AT&T Intellectual Property. All rights reserved. -Overview -======== +NF OAM Adopter Overview +======================= -This document provides an overview of the NF OAM Adopter. \ No newline at end of file +NF OAM Adopter provides FM and PM VES event notification capabilities. + +Main capabilities are: + +- listen for SNMP traps, convert Traps received to VES message format (7.1) and forward it to the VES Collector. +- collect ZIP file of CSV with PM data, translate it to VES message format and forward it to the VES Collector. + +Translation is done via configuration file and it is possible to change it at runtime. + +Project Resources +----------------- + +The source code is available from the Linux Foundation Gerrit server: + +`Gerrit `_ + +The build (CI) jobs are in the Linux Foundation Jenkins server + +`Jenkins `_ + +Issues are tracked in the Linux Foundation Jira server: + +`Jira `_ diff --git a/docs/pm/create-adapter.json b/docs/pm/create-adapter.json new file mode 100644 index 0000000..0fefbf5 --- /dev/null +++ b/docs/pm/create-adapter.json @@ -0,0 +1,7 @@ +{ + "host": "170.10.10.2", + "mechId": { + "username": "user1", + "password": "secretPassword" + } +} diff --git a/docs/pm/get-adapters.json b/docs/pm/get-adapters.json new file mode 100644 index 0000000..5af52bb --- /dev/null +++ b/docs/pm/get-adapters.json @@ -0,0 +1,4 @@ +[ + "170.10.10.2", + "170.10.10.3" +] \ No newline at end of file diff --git a/docs/pm/index.rst b/docs/pm/index.rst new file mode 100644 index 0000000..64d36f7 --- /dev/null +++ b/docs/pm/index.rst @@ -0,0 +1,259 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2021 AT&T Intellectual Property. All rights reserved. + +PM REST Manager +############### + +PM REST Manager library follows `VES Event Listener 7.1 `_ + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + +PM VES Message +============== + +Datatype: commonEventHeader +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Field + - Mandatory + - Default value + - Configurable + - Runtime + - Notes + * - domain + - yes + - measurement + - no + - no + - none + * - eventId + - yes + - none + - yes + - yes + - Unique id generated from combination of multiple fields, selection of fields configurable via mapping config file. + * - eventName + - yes + - PM Notification + - yes + - yes + - value configurable via mapping config file. + * - priority + - yes + - HIGH + - yes + - no + - value configurable via mapping config file. + * - reportingEntityName + - yes + - NF-OAM-ADOPTER + - yes + - yes + - value configurable via mapping config file. + * - startEpochMicrosec + - yes + - none + - none + - yes + - System time at the moment of notification generation + * - lastEpochMicrosec + - yes + - none + - none + - yes + - System time at the moment of notification generation + * - sequence + - yes + - none + - no + - yes + - incremental per line on csv file. Each file will start processing will start from sequence 0. + * - sourceName + - yes + - none + - yes + - yes + - value configurable via mapping config file. + * - version + - yes + - 4.1 + - no + - no + - Library only enforces mandatory fields for 4.1 version + * - vesEventListenerVersion + - yes + - 7.1 + - no + - no + - Library only enforces mandatory fields for 7.1 version + * - eventType + - no + - none + - no + - no + - none + * - nfcNamingCode + - no + - none + - no + - no + - none + * - nfNamingCode + - no + - none + - no + - no + - none + * - nfVendorName + - no + - ISCO + - yes + - no + - value configurable via mapping config file. + * - reportingEntityId + - no + - ONAP-ISCO-ADAPTER + - yes + - no + - value configurable via mapping config file. + * - internalHeader Fields + - no + - none + - no + - no + - none + * - sourceId + - no + - none + - none + - no + - none + * - timeZoneOffset + - no + - none + - no + - no + - none + + +Datatype: measurementFields +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Field + - Mandatory + - Default value + - Configurable + - Runtime + - Notes + * - additionalFields + - no + - none + - yes + - yes + - values configurable via mapping config file. + * - additionalMeasurements + - yes + - none + - yes + - yes + - values configurable via mapping config file. + * - measurementInterval + - yes + - none + - yes + - no + - value configurable via mapping config file. + * - measurementFieldsVersion + - yes + - 4.0 + - no + - no + - none + +REST PM Configuration +===================== + +Rest Adapter configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configuration file **application.yml** contains global definitions required to be consumed by PM REST adapters services. + +- **token-api-username** Defines the username to be used for login +- **synchronization-time-start** Defines the time for execution of pull of PM files and forwarding as VES Message +- **synchronization-time-frequency** Defines the time for execution of pull of PM files and forwarding as VES Message +- **mapping-config-path** Defines the path where mapping configuration file is located + +Rest SB Client Adapter configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **ran-token-endpoint** Defines rand endpoint from where token will be obtained +- **ran-pm-endpoint:** Defines rand endpoint from where ZIP with PM files will be GET. +- **ran-time-zone-offset-endpoint** Defines rand endpoint from where we GET the timezone from the device. + +.. literalinclude:: pm-rest-manager.yaml + :language: YAML + +Mapping Configuration +~~~~~~~~~~~~~~~~~~~~~ + +Configuration file **pm-ves-message-mapping.yaml** contains all definitions required to define the mapping +from ZIP file with collection of csv files information to VES Message format + +.. note:: + File name can be changed as long it matches with configured **mapping-config-path** and file is in yaml format + +- **reporting-entity-name** Reporting entity name assigned to the event +- **reporting-entity-id** Reporting entity id assigned to the event +- **nf-vendor-name** Vendor name assigned to the event +- **event-source-type** Source type assigned to the event +- **event-name** Event name assigned to the event +- **measurement-interval** Interval over which measurements are being reported in seconds +- **priority** Priority assigned to the event + +- **CSV** + - **source-name** Column names containing containing information + - **source-name-regex** The regular expression to which source-name string value is to be matched and removed + - **event-id** Collection of columns names to generate an uniqueID + - **additional-fields** Collection of columns names containing information to be attached + - **additional-measurements-name** Name assigned to AdditionalMeasurement array + - **additional-measurements** Collection of columns names containing information to be attached + - **batch-size** File will be processed and send in small batches event notifications. Size define the number of events which will contain each notification + +.. literalinclude:: pm-ves-message-mapping.yaml + :language: YAML + +PM Adapter Configuration +======================== + +PM Adapters can be instantiated at runtime + +Create a PM Adapter +~~~~~~~~~~~~~~~~~~~ + +**POST** ``https://:/adapters/adapter`` + +.. literalinclude:: create-adapter.json + :language: JSON + +Get PM Adapters +~~~~~~~~~~~~~~~ + +**GET** ``https://:/adapters/`` + +.. literalinclude:: get-adapters.json + :language: JSON + + +Delete PM Adapter +~~~~~~~~~~~~~~~~~ + +**DELETE** ``https://:/adapters/adapter/10.53.40.50`` diff --git a/docs/pm/pm-rest-manager.yaml b/docs/pm/pm-rest-manager.yaml new file mode 100644 index 0000000..747e72c --- /dev/null +++ b/docs/pm/pm-rest-manager.yaml @@ -0,0 +1,7 @@ +pm-rest-manager: + synchronization-time-start: 18:00:00 + synchronization-time-frequency: 60 + mapping-config-path: ${PM_MAPPING_FILE_PATH:mapping-configuration/pm-ves-message-mapping.yaml} + ran-token-endpoint: /auth/token + ran-pm-endpoint: /pm/files + ran-time-zone-offset-endpoint: /system/timeZone \ No newline at end of file diff --git a/docs/pm/pm-ves-message-mapping.yaml b/docs/pm/pm-ves-message-mapping.yaml new file mode 100644 index 0000000..073e3c7 --- /dev/null +++ b/docs/pm/pm-ves-message-mapping.yaml @@ -0,0 +1,26 @@ +reporting-entity-name: "NF-OAM-ADOPTER" +reporting-entity-id: "ONAP-NF-OAM-SOME-VENDOR-ADAPTER" +nf-vendor-name: "SOME-VENDOR" +event-source-type: "SNMP Agent" +event-name: "PM_Notification" +measurement-interval: 40 +priority: "High" +batch-size: 200 +csv: + source-name: Name + event-id: + - PortId + - Date + - Time + additional-fields: + - PortId + - Name + - Date + - Time + additional-measurements-name: "Port measurements" + additional-measurements: + - A_Parameter + - B_Parameter + - C_Parameter + - D_Parameter + - E_Parameter \ No newline at end of file diff --git a/docs/snmp/PortDOWN.json b/docs/snmp/PortDOWN.json new file mode 100644 index 0000000..bc5fbae --- /dev/null +++ b/docs/snmp/PortDOWN.json @@ -0,0 +1,40 @@ +{ + "event":{ + "commonEventHeader":{ + "domain":"fault", + "eventId":"1023555944", + "eventName":"FAULT_NF-OAM-ADOPTER_PortDOWN", + "lastEpochMicrosec":1613592976108880, + "nfVendorName":"SOME-VENDOR", + "priority":"High", + "reportingEntityId":"10283", + "reportingEntityName": "NF-OAM-ADOPTER", + "sequence":0, + "sourceName":"OAM-BOX", + "startEpochMicrosec":1613592976108380, + "timeZoneOffset":"UTC+02:00", + "version":"4.0", + "vesEventListenerVersion":"7.1" + }, + "faultFields":{ + "alarmAdditionalInformation":{ + "1.3.6.1.4.1.1007.0.0.1.0.7":"A0", + "1.3.6.1.4.1.1007.0.0.1.0.5":"1613592976108880", + "1.3.6.1.6.3.1.1.4.1.0":"1.3.6.1.4.1.1007.0.0.1.0.1", + "1.3.6.1.4.1.1007.0.0.1.0.6":"10283", + "1.3.6.1.4.1.1007.0.0.1.0.3":"Port DOWN", + "1.3.6.1.4.1.1007.0.0.1.0.4":"1613592976108380", + "1.3.6.1.4.1.1007.0.0.1.0.2":"OAM-BOX", + "1.3.6.1.2.1.1.3.0":"0:00:50.00" + }, + "alarmCondition":"PortDOWN", + "alarmInterfaceA":"A0", + "eventCategory":"link", + "eventSeverity":"MAJOR", + "eventSourceType":"port", + "faultFieldsVersion":"4.0", + "specificProblem":"Port DOWN", + "vfStatus":"Active" + } + } +} diff --git a/docs/snmp/fm-ves-message-mapping.yaml b/docs/snmp/fm-ves-message-mapping.yaml new file mode 100644 index 0000000..ef9afb7 --- /dev/null +++ b/docs/snmp/fm-ves-message-mapping.yaml @@ -0,0 +1,34 @@ +reporting-entity-name: "NF-OAM-ADOPTER" +reporting-entity-id: "NF-OAM-ADOPTER" +nf-vendor-name: "SOME-VENDOR" +traps: + - oid: "default" + name: "SNMP_Fault" + event-severity: "CRITICAL" + event-source-type: "Unknown" + - oid: "1.3.6.1.4.1.1007.0.0.1.0.1" + name: "PortDOWN" + event-severity: "MAJOR" + event-category: "link" + event-source-type: "port" + oid-event-id: "1.3.6.1.4.1.1007.2.6.9.0" + oid-event-sequence: "0" + oid-reporting-entity-id: "1.3.6.1.4.1.1007.0.0.1.0.6" + oid-source-name: "1.3.6.1.4.1.1007.0.0.1.0.2" + oid-specific-problem-desc: "1.3.6.1.4.1.1007.0.0.1.0.3" + oid-alarm-interface-name: "1.3.6.1.4.1.1007.0.0.1.0.7" + oid-start-epoch-microsec: "1.3.6.1.4.1.1007.0.0.1.0.4" + oid-last-epoch-microsec: "1.3.6.1.4.1.1007.0.0.1.0.5" + - oid: "1.3.6.1.4.1.1007.0.0.1.0.1" + name: "PortUP" + event-severity: "NORMAL" + event-category: "link" + event-source-type: "port" + oid-event-id: "1.3.6.1.4.1.1007.2.6.10.0" + oid-event-sequence: "0" + oid-reporting-entity-id: "1.3.6.1.4.1.1007.0.0.1.0.6" + oid-source-name: "1.3.6.1.4.1.1007.0.0.1.0.2" + oid-specific-problem-desc: "1.3.6.1.4.1.1007.0.0.1.0.3" + oid-alarm-interface-name: "1.3.6.1.4.1.1007.0.0.1.0.7" + oid-start-epoch-microsec: "1.3.6.1.4.1.1007.0.0.1.0.4" + oid-last-epoch-microsec: "1.3.6.1.4.1.1007.0.0.1.0.5" \ No newline at end of file diff --git a/docs/snmp/index.rst b/docs/snmp/index.rst new file mode 100644 index 0000000..5dbe202 --- /dev/null +++ b/docs/snmp/index.rst @@ -0,0 +1,253 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2021 AT&T Intellectual Property. All rights reserved. + +SNMP2VES Manager +################ + +SNMP Manager library follows `VES Event Listener 7.1 `_ + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + +FM VES Message +-------------- + +Datatype: commonEventHeader +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Field + - Mandatory + - Default value + - Configurable + - Runtime + - Notes + * - domain + - yes + - fault + - no + - no + - none + * - eventId + - yes + - SNMP Trap RequestID + - yes + - yes + - Uses default defined value if TRAP OID not configured + * - eventName + - yes + - SNMP Fault + - yes + - yes + - Uses default defined value if TRAP OID not configured + * - priority + - yes + - HIGH + - no + - no + - none + * - reportingEntityName + - yes + - NF-OAM-ADOPTER + - yes + - yes + - set value if provided by notification trap and oid-reporting-entity-name configured. + * - startEpochMicrosec + - yes + - System time at the moment of notification generation + - yes + - yes + - set value if provided by notification trap and oid-start-epoch-microsec configured. + * - lastEpochMicrosec + - yes + - System time at the moment of notification generation + - yes + - yes + - set value if provided by notification trap and oid-last-epoch-microsec configured. + * - sequence + - yes + - 0 + - yes + - yes + - set value if provided by notification trap and oid-event-sequence configured. + * - sourceName + - yes + - Host Address of SNMP Agent sending the trap notification + - yes + - yes + - set value if provided by notification trap and oid-source-name configured. + * - version + - yes + - 4.1 + - yes + - no + - Library only enforces mandatory fields for 4.1 version + * - vesEventListenerVersion + - yes + - 7.1 + - none + - no + - Library only enforces mandatory fields for 7.1 version + * - eventType + - no + - none + - no + - no + - none + * - nfcNamingCode + - no + - none + - no + - no + - none + * - nfNamingCode + - no + - none + - no + - no + - none + * - nfVendorName + - no + - NF-OAM-ADOPTER-VENDOR + - yes + - no + - none + * - reportingEntityId + - no + - none + - no + - yes + - set value if provided by notification trap and oid-reporting-entity-id configured. + * - internalHeader Fields + - no + - none + - no + - no + - none + * - sourceId + - no + - none + - none + - no + - none + * - timeZoneOffset + - no + - none + - no + - no + - none + +Datatype: faultFields +~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Field + - Mandatory + - Default value + - Configurable + - Runtime + - Notes + * - alarmCondition + - yes + - SNMP Fault + - yes + - yes + - set value if provided by notification trap and trap configured. + * - eventSeverity + - yes + - CRITICAL + - yes + - yes + - set value if provided by notification trap and event-severity configured. + * - eventSourceType + - yes + - SNMP Agent + - yes + - no + - none + * - faultFieldsVersion + - yes + - 4.0 + - no + - no + - none + * - specificProblem + - yes + - SNMP Fault + - no + - yes + - set value if provided by notification trap and oid-specific-problem-desc configured. + * - vfStatus + - yes + - ACTIVE + - no + - no + - none + * - eventCategory + - no + - none + - no + - yes + - set value if provided by notification trap and event-category configured. + * - alarmAdditional Information + - no + - no + - no + - yes + - Map of OID with values + * - alarmInterfaceA + - no + - none + - no + - yes + - set value if provided by notification trap and oid-alarm-interface-name configured. + +Mapping Configuration +--------------------- + +Configuration file **fm-ves-message-mapping.yaml** contains all definitions required to define the mapping +from trap provided information to VES Message format + +**trap mapping example** + +.. literalinclude:: fm-ves-message-mapping.yaml + :language: YAML + +- **global** + + - **reporting-entity-name** Reporting entity name assigned to the event + - **reporting-entity-id** Reporting entity id assigned to the event + - **nf-vendor-name** Vendor name assigned to the event + +- **traps** + - **oid** *OID* trap identifier + - **name** Name of the trap + - **event-severity** Severity assigned to the event + - **event-category** Category assigned to the event + - **event-source-type** Source type assigned to the event + - **oid-event-id** *OID* containing the event entity id e.g. port interface + - **oid-event-sequence** Event sequence 0 on a raise and 1 on a clear + - **oid-reporting-entity-id** *OID* containing the reporting entity id + - **oid-source-name** *OID* containing the source name + - **oid-specific-problem-desc** *OID* containing the trap problem description + - **oid-start-epoch-microsec** *OID* containing the alarm start epoch + - **oid-last-epoch-microsec** *OID* containing the alarm last epoch + - **oid-alarm-interface-name** *OID* containing the interface name + +**Output example for port down trap** + +.. literalinclude:: PortDOWN.json + :language: JSON + +**Output example for any undefined trap** + +Undefined trap will use the mapping defined for default. + +.. literalinclude:: unknown-trap.json + :language: JSON \ No newline at end of file diff --git a/docs/snmp/snmp-manager.yaml b/docs/snmp/snmp-manager.yaml new file mode 100644 index 0000000..5ca9c70 --- /dev/null +++ b/docs/snmp/snmp-manager.yaml @@ -0,0 +1,4 @@ +snmp-manager: + host: "0.0.0.0" + port: 162 + mapping-config-path: "mapping-configuration/fm-ves-message-mapping.yaml" \ No newline at end of file diff --git a/docs/snmp/unknown-trap.json b/docs/snmp/unknown-trap.json new file mode 100644 index 0000000..a0e8e3f --- /dev/null +++ b/docs/snmp/unknown-trap.json @@ -0,0 +1,33 @@ +{ + "event": { + "commonEventHeader": { + "domain": "fault", + "eventId": "46102539", + "eventName":"FAULT_NF-OAM-ADOPTER_SNMP_Fault", + "lastEpochMicrosec": 1.601542425363E12, + "nfVendorName": "SOME-VENDOR", + "priority": "High", + "reportingEntityName": "NF-OAM-ADOPTER", + "sequence": 0, + "sourceName": "127.0.0.1", + "startEpochMicrosec":1613592976108380, + "timeZoneOffset":"UTC+02:00", + "version": "4.0", + "vesEventListenerVersion": "7.1" + }, + "faultFields": { + "alarmAdditionalInformation": { + "1.3.6.1.6.3.1.1.4.1.0": "1.2.3.4.5", + "1.2.3.4.5": "some string", + "1.3.6.1.2.1.1.1.0": "System Description", + "1.3.6.1.2.1.1.3.0": "0:00:50.00" + }, + "alarmCondition": "SNMP_Fault", + "eventSeverity": "CRITICAL", + "eventSourceType": "Unknown", + "faultFieldsVersion": "4.0", + "specificProblem": "SNMP_Fault", + "vfStatus": "Active" + } + } +} diff --git a/docs/user-guide.rst b/docs/user-guide.rst index cd389ba..4380a54 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -2,7 +2,12 @@ .. SPDX-License-Identifier: CC-BY-4.0 .. Copyright (C) 2021 AT&T Intellectual Property. All rights reserved. -User Guide -========== +NF OAM Adopter User Guide +========================= -This document provides a quickstart for users of the NF OAM Adopter. \ No newline at end of file +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + ./snmp/index.rst + ./pm/index.rst \ No newline at end of file