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
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
.. 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 <https://gerrit.o-ran-sc.org/r/admin/repos/oam/nf-oam-adopter/>`_
+
+The build (CI) jobs are in the Linux Foundation Jenkins server
+
+`Jenkins <https://jenkins.o-ran-sc.org/view/oam-nf-oam-adopter/>`_
+
+Issues are tracked in the Linux Foundation Jira server:
+
+`Jira <https://jira.o-ran-sc.org/projects/OAM/issues>`_
--- /dev/null
+{
+ "host": "170.10.10.2",
+ "mechId": {
+ "username": "user1",
+ "password": "secretPassword"
+ }
+}
--- /dev/null
+[
+ "170.10.10.2",
+ "170.10.10.3"
+]
\ No newline at end of file
--- /dev/null
+.. 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 <https://docs.onap.org/projects/onap-vnfrqts-requirements/en/latest/Chapter8/ves7_1spec.html#>`_
+
+.. 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://<SERVICE_IP>:<SERVICE_PORT>/adapters/adapter``
+
+.. literalinclude:: create-adapter.json
+ :language: JSON
+
+Get PM Adapters
+~~~~~~~~~~~~~~~
+
+**GET** ``https://<SERVICE_IP>:<SERVICE_PORT>/adapters/``
+
+.. literalinclude:: get-adapters.json
+ :language: JSON
+
+
+Delete PM Adapter
+~~~~~~~~~~~~~~~~~
+
+**DELETE** ``https://<SERVICE_IP>:<SERVICE_PORT>/adapters/adapter/10.53.40.50``
--- /dev/null
+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
--- /dev/null
+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
--- /dev/null
+{
+ "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"
+ }
+ }
+}
--- /dev/null
+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
--- /dev/null
+.. 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 <https://docs.onap.org/projects/onap-vnfrqts-requirements/en/latest/Chapter8/ves7_1spec.html#>`_
+
+.. 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
--- /dev/null
+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
--- /dev/null
+{
+ "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"
+ }
+ }
+}
.. 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
Code Review / oam / nf-oam-adopter.git / commitdiff
