From 9847631e1be786f37aef897d4216b6bc2bfa16a2 Mon Sep 17 00:00:00 2001 From: Rich Bennett Date: Sat, 25 Aug 2018 10:43:15 -0400 Subject: Add RST Files for SNMPTRAP Submitting RST files from abandoned patch https://gerrit.onap.org/r/57071 With updates to remove sphinx warnings Change-Id: I18da62f59943bb932bcfdd6bddfc9164d8ae9b93 Issue-ID: DCAEGEN2-624 Signed-off-by: Rich Bennett --- docs/sections/services/snmptrap/administration.rst | 45 ++++ docs/sections/services/snmptrap/architecture.rst | 85 +++++++ docs/sections/services/snmptrap/configuration.rst | 114 +++++++++ docs/sections/services/snmptrap/delivery.rst | 18 ++ .../sections/services/snmptrap/humaninterfaces.rst | 31 +++ docs/sections/services/snmptrap/index.rst | 12 +- docs/sections/services/snmptrap/installation.rst | 39 +++ docs/sections/services/snmptrap/logging.rst | 261 +++++++++++++++++++++ docs/sections/services/snmptrap/offeredapis.rst | 61 +++++ docs/sections/services/snmptrap/release-notes.rst | 45 ++++ 10 files changed, 710 insertions(+), 1 deletion(-) create mode 100644 docs/sections/services/snmptrap/administration.rst create mode 100644 docs/sections/services/snmptrap/architecture.rst create mode 100644 docs/sections/services/snmptrap/configuration.rst create mode 100644 docs/sections/services/snmptrap/delivery.rst create mode 100644 docs/sections/services/snmptrap/humaninterfaces.rst create mode 100644 docs/sections/services/snmptrap/installation.rst create mode 100644 docs/sections/services/snmptrap/logging.rst create mode 100644 docs/sections/services/snmptrap/offeredapis.rst create mode 100644 docs/sections/services/snmptrap/release-notes.rst diff --git a/docs/sections/services/snmptrap/administration.rst b/docs/sections/services/snmptrap/administration.rst new file mode 100644 index 00000000..950badac --- /dev/null +++ b/docs/sections/services/snmptrap/administration.rst @@ -0,0 +1,45 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Administration +============== + +Processes +--------- + +**SNMPTRAP** runs as a single (python) process inside the container. You can find it using the following commands: + +Inside the container +^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + `ps -ef | grep snmptrap.py | grep -v grep` + + +Outside the container +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + docker exec -it `ps -ef | grep snmptrap.py | grep -v grep` + + +Actions +------- + +The **SNMPTRAP** container can be monitored for status by running the command: + +.. code-block:: bash + + `bin/snmptrapd.sh status` + +Output from this command will be two-fold. First will be the textual response: + + `Stopping snmptrap... Stopped.` + +Also available is the return code of the command: + + 0 - if command executed successfully + 1 - if the command failed, and/or the process is not running + + diff --git a/docs/sections/services/snmptrap/architecture.rst b/docs/sections/services/snmptrap/architecture.rst new file mode 100644 index 00000000..f50f1d37 --- /dev/null +++ b/docs/sections/services/snmptrap/architecture.rst @@ -0,0 +1,85 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Architecture +============ + +**SNMPTRAP** (or "trapd", as in trap daemon) is a network facing ONAP platform +component. + +The simple network management protocol (or "SNMP", for short) is a +standardized communication protocol used between managed devices (physical, +virtual - or anything in between!) and a management system. It is used to +relay data that can be valuable in the operation, fault identification and +planning processes of all networks. + +It is the "front line" of management in all environments. + +SNMP utilizes a message called a "trap" to inform SNMP managers of abnormal +or changed conditions on a resource that is running a SNMP agent. These +agents can run on physical or virtual resources (no difference in reporting) +and can notify on anything from hardware states, resource utilization, +software processes or anything else specific to the agent's environment. + + +Capabilities +------------ + +**SNMPTRAP** receives simple network management protocol ("SNMP") traps +and publishes them to a message router (DMAAP/MR) instance based on +attributes obtained from configuration binding service ("CBS"). + +.. blockdiag:: + + blockdiag layers { + orientation = portrait + snmp_agent_1 -> SNMPTRAP; + snmp_agent_2 -> SNMPTRAP; + snmp_agent_n -> SNMPTRAP; + config binding service -> SNMPTRAP; + SNMPTRAP -> dmaap mr; + + group l1 { + color = orange; + snmp_agent_1; snmp_agent_2; snmp_agent_n; + } + group l2 { + color = blue; + SNMPTRAP; + } + group l3 { + color = orange; + dmaap mr; + } + group l4 { + color = gray; + config binding service; + } + + } + + +Interactions +------------ + + +Traps are published to DMAAP/MR in a json format. Once traps are published +to a DMAAP/MR instance, they are available to consumers that are +subscribed to the topic they were published to. + + +Usage Scenarios +--------------- + +**SNMPTRAP** can be run on any device (physical, logical, container) that +is capable of running python 3.6+ and has SNMP traps targeted at it. Running +an instance of **SNMPTRAP** will result in arriving traps being published +to the topic specified by config binding services. If CBS is not present, +SNMPTRAP will look for or a JSON configuration file specified via the +environment vvariable CBS_SIM_JSON at startup. Note that relative paths +will be located from the bin (/bin directory. E.g. + +.. code-block:: bash + + CBS_SIM_JSON=../etc/snmptrapd.json + diff --git a/docs/sections/services/snmptrap/configuration.rst b/docs/sections/services/snmptrap/configuration.rst new file mode 100644 index 00000000..2c8afe23 --- /dev/null +++ b/docs/sections/services/snmptrap/configuration.rst @@ -0,0 +1,114 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Configuration +============= + +**SNMPTRAP** configuration is controlled via a single JSON 'transaction'. +This transaction can be: + + - a reply from config binding services + + - a locally hosted JSON file + +The format of this message is described in the SNMPTRAP package, under: + + ``/spec/snmptrap-collector-component-spec.json`` + +There should also be a template JSON file with example/default values found at: + + ``/etc/snmptrapd.json`` + +If you are going to use a local file, the env variable below must be defined before SNMPTRAP runs. There is a default value set in the SNMPTRAP startup script (bin/snmptrapd.sh): + + ``export CBS_SIM_JSON=../etc/snmptrapd.json`` + +In either scenario, the format of the config message/transaction is the same. An example is described below. + +JSON CONFIG +^^^^^^^^^^^ + +The format of the JSON configuration that drives all behavior of SNMPTRAP is probably best described using an example. One can be found below: + +.. code-block:: json + + { + "snmptrapd": { + "version": "1.3.0", + "title": "ONAP SNMP Trap Receiver" + }, + "protocols": { + "transport": "udp", + "ipv4_interface": "0.0.0.0", + "ipv4_port": 6162, + "ipv6_interface": "::1", + "ipv6_port": 6162 + }, + "cache": { + "dns_cache_ttl_seconds": 60 + }, + "publisher": { + "http_timeout_milliseconds": 1500, + "http_retries": 3, + "http_milliseconds_between_retries": 750, + "http_primary_publisher": "true", + "http_peer_publisher": "unavailable", + "max_traps_between_publishes": 10, + "max_milliseconds_between_publishes": 10000 + }, + "streams_publishes": { + "sec_fault_unsecure": { + "type": "message_router", + "aaf_password": null, + "dmaap_info": { + "location": "mtl5", + "client_id": null, + "client_role": null, + "topic_url": "http://localhost:3904/events/ONAP-COLLECTOR-SNMPTRAP" + }, + "aaf_username": null + } + }, + "files": { + "runtime_base_dir": "/opt/app/snmptrap", + "log_dir": "logs", + "data_dir": "data", + "pid_dir": "tmp", + "arriving_traps_log": "snmptrapd_arriving_traps.log", + "snmptrapd_diag": "snmptrapd_prog_diag.log", + "traps_stats_log": "snmptrapd_stats.csv", + "perm_status_file": "snmptrapd_status.log", + "eelf_base_dir": "/opt/app/snmptrap/logs", + "eelf_error": "error.log", + "eelf_debug": "debug.log", + "eelf_audit": "audit.log", + "eelf_metrics": "metrics.log", + "roll_frequency": "hour", + "minimum_severity_to_log": 2 + }, + "trap_config": { + "sw_interval_in_seconds": 60, + "notify_oids": { + ".1.3.6.1.4.1.9.0.1": { + "sw_high_water_in_interval": 102, + "sw_low_water_in_interval": 7, + "category": "logonly" + }, + ".1.3.6.1.4.1.9.0.2": { + "sw_high_water_in_interval": 101, + "sw_low_water_in_interval": 7, + "category": "logonly" + }, + ".1.3.6.1.4.1.9.0.3": { + "sw_high_water_in_interval": 102, + "sw_low_water_in_interval": 7, + "category": "logonly" + }, + ".1.3.6.1.4.1.9.0.4": { + "sw_high_water_in_interval": 10, + "sw_low_water_in_interval": 3, + "category": "logonly" + } + } + } + } diff --git a/docs/sections/services/snmptrap/delivery.rst b/docs/sections/services/snmptrap/delivery.rst new file mode 100644 index 00000000..fe861b0b --- /dev/null +++ b/docs/sections/services/snmptrap/delivery.rst @@ -0,0 +1,18 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Delivery +======== + +**SNMPTRAP** is delivered as a docker container. The host or VM that will +run this container must have the docker application loaded and available +to the userID that will be running the SNMPTRAP container. + +The following command will download the latest SNMPTRAP container from +nexus and launch it in the container named "SNMPTRAP": + +.. code-block:: bash + + docker run --detach -t --rm -p 162:6162/udp -P --name=SNMPTRAP nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.snmptrap ./bin/snmptrapd.sh start + + diff --git a/docs/sections/services/snmptrap/humaninterfaces.rst b/docs/sections/services/snmptrap/humaninterfaces.rst new file mode 100644 index 00000000..53f8adcd --- /dev/null +++ b/docs/sections/services/snmptrap/humaninterfaces.rst @@ -0,0 +1,31 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Human Interfaces +================ + +Graphical +^^^^^^^^^ + +There are no graphical interfaces for snmptrap. + +Command Line +^^^^^^^^^^^^ + +There is a command line interface available, which is a shell script +that provides all needed interactions with **SNMPTRAP**. + +Usage +""""" + + ``bin/snmptrapd.sh [start|stop|restart|status|reloadCfg]`` + + start - start an instance of snmptrapd inside the container + + stop - terminate the snmptrapd process currently running inside container + + restart - start an instance of snmptrapd inside current container + + status - check and display status of snmptrapd inside container + + reloadCfg - signal current instance of snmptrapd to re-request configuration from Config Binding Service diff --git a/docs/sections/services/snmptrap/index.rst b/docs/sections/services/snmptrap/index.rst index 5d662e0d..0a27cdd8 100644 --- a/docs/sections/services/snmptrap/index.rst +++ b/docs/sections/services/snmptrap/index.rst @@ -7,5 +7,15 @@ SNMP TRAP COLLECTOR MS (DCAE) .. Add or remove sections below as appropriate for the platform component. -Trap collector overview and functions to be listed +.. toctree:: + :maxdepth: 1 + ./architecture.rst + ./delivery.rst + ./offeredapis.rst + ./logging.rst + ./installation.rst + ./configuration.rst + ./administration.rst + ./humaninterfaces.rst + ./release-notes.rst diff --git a/docs/sections/services/snmptrap/installation.rst b/docs/sections/services/snmptrap/installation.rst new file mode 100644 index 00000000..3fbb4cde --- /dev/null +++ b/docs/sections/services/snmptrap/installation.rst @@ -0,0 +1,39 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Installation +============ + +**SNMPTRAP** is delivered as a docker container. The host or VM that +will run this container must have the docker application loaded and +available to the userID that will be running the SNMPTRAP container. + +The instructions below will download and run the latest SNMPTRAP +container from the NEXUS repository. + +Environment +----------- + +An environment suitable for running docker containers is recommended. +If that is not available, SNMPTRAP source can be downloaded and run +in a VM or on baremetal. + +If running from a docker container, it is assumed that the config +binding service has been installed and is successfully instantiating +container configurations as needed. + +Also required is a working DMAAP/MR message router environment. SNMPTRAP +publishes traps to DMAAP/MR as JSON messages, and expect the host +resources and publishing credentials to be included in the CONFIG +BINDING SERVICE config. + +Steps +----- + +The following command will download the latest snmptrap container +from nexus and launch it in the container named "snmptrap": + +.. code-block:: bash + + docker run --detach -t --rm -p 162:6162/udp -P --name=snmptrap nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.snmptrap ./bin/snmptrapd.sh start + diff --git a/docs/sections/services/snmptrap/logging.rst b/docs/sections/services/snmptrap/logging.rst new file mode 100644 index 00000000..a7109a00 --- /dev/null +++ b/docs/sections/services/snmptrap/logging.rst @@ -0,0 +1,261 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Logging +======= + +Logging is controlled by the configuration provided to **SNMPTRAP** by CBS, +or via the fallback config file specified as the environment +variable "CBS_SIM_JSON" at startup. The section of that JSON configuration +that influences the various forms of application logging is referenced +throughout this document, with examples. + +Using the JSON configuration, a base directory is specified for application +data and EELF log files. Specific filenames (again, from the JSON +config) are appended to the base directory value to create a full-path +filename for use by SNMPTRAP. + +Also available is the ability to modify how frequently logs are rolled to +time-stamped versions (and a new empty file is started) as well as what +severity level to log to program diagnostic logs. Files will be rolled to +an archived/timestamped version hourly. The actual archival (to a +timestamped filename) occurs when the first trap is +received **in a new hour** (or minute, or day - depending +on "roll_frequency" value). + +Defaults are shown below: + +.. code-block:: json + + "files": { + + ... + "roll_frequency": "hour", + "minimum_severity_to_log": 2 + + ... + }, + + +Where to Access Information: APPLICATION DATA (TRAPS) +----------------------------------------------------- + +APPLICATION DATA (TRAPS) +^^^^^^^^^^^^^^^^^^^^^^^^ + +**SNMPTRAP** produces application-specific logs (e.g. trap logs/payloads, +etc) as well as various other statistical and diagnostic logs. The +location of these logs is controlled by the JSON config, using these +values: + +.. code-block:: json + + "files": { + "**runtime_base_dir**": "/opt/app/snmptrap", + "log_dir": "logs", + "data_dir": "data", + "pid_dir": "tmp", + "arriving_traps_log": "snmptrapd_arriving_traps.log", + "snmptrapd_diag": "snmptrapd_prog_diag.log", + "traps_stats_log": "snmptrapd_stats.csv", + "perm_status_file": "snmptrapd_status.log", + "roll_frequency": "hour", + "minimum_severity_to_log": 2 + + ... + }, + +The base directory for all data logs is specified with: + + **runtime_base_dir** + +Remaining log file references are appended to the *runtime_base_dir* +value to specify a logfile location. The result using the +above example would create the files: + +.. code-block:: bash + + /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log + /opt/app/snmptrap/logs/snmptrapd_prog_diag.log + /opt/app/snmptrap/logs/snmptrapd_stats.csv + /opt/app/snmptrap/logs/snmptrapd_status.log + + +ARRIVING TRAPS +^^^^^^^^^^^^^^^ + +**SNMPTRAP** logs all arriving traps. These traps are saved in a +filename created by appending *runtime_base_dir*, *log_dir* +and *arriving_traps_log* from the JSON config. Using the example +above, the resulting arriving trap log would be: + +.. code-block:: bash + + /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log + +An example from this log is shown below: + +.. code-block:: none + + 1529960544.4896748 Mon Jun 25 17:02:24 2018; Mon Jun 25 17:02:24 2018 com.att.dcae.dmaap.IST3.DCAE-COLLECTOR-UCSNMP 15299605440000 1.3.6.1.4.1.999.0.1 server001 127.0.0.1 server001 v2c 751564798 0f40196a-78bb-11e8-bac7-005056865aac , "varbinds": [{"varbind_oid": "1.3.6.1.4.1.999.0.1.1", "varbind_type": "OctetString", "varbind_value": "TEST TRAP"}] + +*(Add: varbind type enumerations)* + +PUBLISHED TRAPS +^^^^^^^^^^^^^^^ + +SNMPTRAP's first priority is to receive and decode SNMP traps, then +publish the results to a configured DMAAP/MR message bus. Traps that +are successfully published (e.g. publish attempt gets a "200/ok" +response from the DMAAP/MR server) are logged to a file named by +the technology being used combined with the topic being published to. + +If you find a trap in this published log, it has been acknowledged as +received by DMAAP/MR. If consumers complain of "missing traps", the +source of the problem will be downstream (*not with SNMPTRAP*) if +the trap has been logged here. + +For example, with a json config of: + +.. code-block:: json + + "dmaap_info": { + "location": "mtl5", + "client_id": null, + "client_role": null, + "topic_url": "http://172.17.0.1:3904/events/ONAP-COLLECTOR-SNMPTRAP" + +and + +.. code-block:: json + + "files": { + "**runtime_base_dir**": "/opt/app/snmptrap", + +result in traps that are confirmed (200/ok) as published logged to the file: + +.. code-block:: bash + + /opt/app/snmptrap/logs/DMAAP_ONAP-COLLECTOR-SNMPTRAP.json + +An example from this JSON log is shown below: + +.. code-block:: json + + { + "uuid": "0f40196a-78bb-11e8-bac7-005056865aac", + "agent address": "127.0.0.1", + "agent name": "server001", + "cambria.partition": "server001", + "community": "", + "community len": 0, + "epoch_serno": 15299605440000, + "protocol version": "v2c", + "time received": 1529960544.4896748, + "trap category": "DCAE-COLLECTOR-UCSNMP", + "sysUptime": "751564798", + "notify OID": "1.3.6.1.4.1.999.0.1", + "notify OID len": 9, + "varbinds": [ + { + "varbind_oid": "1.3.6.1.4.1.999.0.1.1", + "varbind_type": "OctetString", + "varbind_value": "TEST TRAP" + } + ] + } + + + +EELF +^^^^ + +For program/operational logging, **SNMPTRAP** follows the EELF logging +convention. Please be aware that the EELF specification results in +messages spread across various files. Some work may be required to +find the right location (file) that contains the message you are +looking for. + +EELF logging is controlled by the configuration provided +to **SNMPTRAP** by CBS, or via the fallback config file specified +as an environment variable "CBS_SIM_JSON" at startup. The section +of that JSON configuration that influences EELF logging is: + +.. code-block:: json + + "files": { + + ... + "**eelf_base_dir**": "/opt/app/snmptrap/logs", + "eelf_error": "error.log", + "eelf_debug": "debug.log", + "eelf_audit": "audit.log", + "eelf_metrics": "metrics.log", + "roll_frequency": "hour", + }, + + ... + + +The base directory for all EELF logs is specified with: + + **eelf_base_dir** + +Remaining eelf_ references are appended to the eelf_base_dir value +to specify a logfile location. The result using the above example would +create the files: + +.. code-block:: bash + + /opt/app/snmptrap/logs/error.log + /opt/app/snmptrap/logs/debug.log + /opt/app/snmptrap/logs/audit.log + /opt/app/snmptrap/logs/metrics.log + +Again using the above example configuration, these files will be rolled +to an archived/timestamped version hourly. The actually archival (to a +timestamped filename) occurs when the first trap is +received **in a new hour** (or minute, or day - depending +on "roll_frequency" value). + +Error / Warning Messages +------------------------ + +Program Diagnostics +^^^^^^^^^^^^^^^^^^^ + +Detailed application log messages can be found in "snmptrapd_diag" (JSON +config reference). These can be very verbose and roll quickly +depending on trap arrival rates, number of varbinds encountered, +minimum_severity_to_log setting in JSON config, etc. + +In the default config, this file can be found at: + +.. code-block:: bash + + /opt/app/snmptrap/logs/snmptrapd_diag.log + +Messages will be in the general format of: + +.. code-block:: none + + 2018-04-25T17:28:10,305||snmptrapd||||INFO|100||arriving traps logged to: /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log + 2018-04-25T17:28:10,305||snmptrapd||||INFO|100||published traps logged to: /opt/app/snmptrap/logs/DMAAP_com.att.dcae.dmaap.IST3.DCAE-COLLECTOR-UCSNMP.json + 2018-04-25T17:28:10,306||snmptrapd||||INFO|100||Runtime PID file: /opt/app/snmptrap/tmp/snmptrapd.py.pid + 2018-04-25T17:28:48,019|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||snmp trap arrived from 192.168.1.139, assigned uuid: 1cd77e98-48ae-11e8-98e5-005056865aac + 2018-04-25T17:28:48,023|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||dns cache expired or missing for 192.168.1.139 - refreshing + 2018-04-25T17:28:48,027|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||cache for server001 (192.168.1.139) updated - set to expire at 1524677388 + 2018-04-25T17:28:48,034|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||snmp trap arrived from 192.168.1.139, assigned uuid: 0f40196a-78bb-11e8-bac7-005056 + 2018-04-25T17:28:48,036|notif_receiver_cb|snmptrapd||||DETAILED|100||processing varbinds for 0f40196a-78bb-11e8-bac7-005056 + 2018-04-25T17:28:48,040|notif_receiver_cb|snmptrapd||||DETAILED|100||adding 0f40196a-78bb-11e8-bac7-005056 to buffer + + 2018-06-25T21:02:24,491|notif_receiver_cb|snmptrapd||||DETAILED|100||trap 0f40196a-78bb-11e8-bac7-005056865aac : {"uuid": "0f40196a-78bb-11e8-bac7-005056865aac", "agent address": "192.168.1.139", "agent name": "server001", "cambria.partition": "server001", "community": "", "community len": 0, "epoch_serno": 15299605440000, "protocol version": "v2c", "time received": 1529960544.4896748, "trap category": "com.att.dcae.dmaap.IST3.DCAE-COLLECTOR-UCSNMP", "sysUptime": "751564798", "notify OID": "1.3.6.1.4.1.999.0.1", "notify OID len": 9, "varbinds": [{"varbind_oid": "1.3.6.1.4.1.999.0.1.1", "varbind_type": "OctetString", "varbind_value": "TEST TRAP"}]} + 2018-06-25T21:02:24,496|post_dmaap|snmptrapd||||DETAILED|100||post_data_enclosed: {"uuid": "0f40196a-78bb-11e8-bac7-005056865aac", "agent address": "192.168.1.139", "agent name": "server001", "cambria.partition": "server001", "community": "", "community len": 0, "epoch_serno": 15299605440000, "protocol version": "v2c", "time received": 1529960544.4896748, "trap category": "com.att.dcae.dmaap.IST3.DCAE-COLLECTOR-UCSNMP", "sysUptime": "751564798", "notify OID": "1.3.6.1.4.1.999.0.1", "notify OID len": 9, "varbinds": [{"varbind_oid": "1.3.6.1.4.1.999.0.1.1", "varbind_type": "OctetString", "varbind_value": "TEST TRAP"}]} + + +Platform Status +^^^^^^^^^^^^^^^ + +.. code-block:: json + + "perm_status_file": "snmptrapd_status.log", diff --git a/docs/sections/services/snmptrap/offeredapis.rst b/docs/sections/services/snmptrap/offeredapis.rst new file mode 100644 index 00000000..e9a8afeb --- /dev/null +++ b/docs/sections/services/snmptrap/offeredapis.rst @@ -0,0 +1,61 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Offered APIs +============ + +**SNMPTRAP** supports the Simple Network Management Protocol (SNMP) +standard. It is a well documented and pervasive protocol, +used in all networks worldwide. + +As an API offering, the only way to interact with **SNMPTRAP** is +to send traps that conform to the industry standard specification +(RFC1215 - available at https://tools.ietf.org/html/rfc1215 ) to a +running instance. To accomplish this, you may: + +1. Configure SNMP agents to send native traps to a SNMPTRAP instance. + In SNMP agent configurations, this is usually accomplished by + setting the "trap target" or "snmp manager" to the IP address + of the running VM/container hosting SNMPTRAP. + +2. Mimic a SNMP trap using various freely available utilities. Two + examples are provided below, be sure to change the target + ("localhost") and port ("162") to applicable values in your + environment. + +Net-SNMP +-------- + +.. code-block:: bash + + snmptrap -d -v 1 -c public ${to_ip_address}:${to_portt} .1.3.6.1.4.1.99999 localhost 6 1 '55' .1.11.12.13.14.15 s "test trap" + +.. note:: + + This will display some "read_config_store open failure" errors; + they can be ignored, the trap has successfully been sent to the + specified destination. + +pysnmp +------ + +.. code-block:: python + + from pysnmp.hlapi import * + from pysnmp import debug + + # debug.setLogger(debug.Debug('msgproc')) + + errorIndication, errorStatus, errorIndex, varbinds = next(sendNotification(SnmpEngine(), + CommunityData('not_public'), + UdpTransportTarget(('localhost', 162)), + ContextData(), + 'trap', + [ObjectType(ObjectIdentity('.1.3.6.1.4.1.999.1'), OctetString('test trap - ignore')), + ObjectType(ObjectIdentity('.1.3.6.1.4.1.999.2'), OctetString('ONAP pytest trap'))]) + ) + + if errorIndication: + print(errorIndication) + else: + print("successfully sent first trap example, number %d" % i) diff --git a/docs/sections/services/snmptrap/release-notes.rst b/docs/sections/services/snmptrap/release-notes.rst new file mode 100644 index 00000000..45a0f152 --- /dev/null +++ b/docs/sections/services/snmptrap/release-notes.rst @@ -0,0 +1,45 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Release Notes +============= + +.. note:: + * This Release Notes must be updated each time the team decides to Release new artifacts. + * The scope of this Release Notes is for this particular component. In other words, each ONAP component has its Release Notes. + * This Release Notes is cumulative, the most recently Released artifact is made visible in the top of this Release Notes. + * Except the date and the version number, all the other sections are optional but there must be at least one section describing the purpose of this new release. + * This note must be removed after content has been added. + + +Version: 1.3.0 +-------------- + + +:Release Date: 2018-05-02 + + +**New Features** + +Support for config binding services. + +**Bug Fixes** + - `https://jira.onap.org/browse/DCAEGEN2-465` +**Known Issues** + - `https://jira.onap.org/browse/DCAEGEN2-465` + Default config causes standalone instance startup failure. + +**Security Issues** + - None + + +**Upgrade Notes** + +**Deprecation Notes** + +**Other** + +=========== + +End of Release Notes -- cgit 1.2.3-korg