diff options
Diffstat (limited to 'docs/sections/services/snmptrap')
| -rw-r--r-- | docs/sections/services/snmptrap/administration.rst | 8 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/architecture.rst | 10 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/configuration.rst | 4 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/delivery.rst | 1 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/installation.rst | 21 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/logging.rst | 48 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/offeredapis.rst | 18 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/release-notes.rst | 11 |
8 files changed, 58 insertions, 63 deletions
diff --git a/docs/sections/services/snmptrap/administration.rst b/docs/sections/services/snmptrap/administration.rst index ab5ec6e2..44948174 100644 --- a/docs/sections/services/snmptrap/administration.rst +++ b/docs/sections/services/snmptrap/administration.rst @@ -23,7 +23,7 @@ The **trapd** service can be started by running the command: Output from this command will be two-fold. First will be the textual response: -.. code-block:: bash +.. code-block:: none 2018-10-16T15:14:59,461 Starting snmptrapd... 2018-10-16T19:15:01,966 ONAP controller not present, trying json config override via CBS_SIM_JSON env variable @@ -45,7 +45,7 @@ The **trapd** container can be monitored for status by running this command from If **SNMPTRAPD** is present/running, output from this command will be: -.. code-block:: bash +.. code-block:: none 2018-10-16T15:01:47,705 Status: snmptrapd running ucsnmp 16109 16090 0 Oct08 ? 00:07:16 python ./snmptrapd.py @@ -61,7 +61,7 @@ and the return code presented to the shell upon exit: If **trapd** is not present, output from this command will be: -.. code-block:: bash +.. code-block:: none 2018-10-16T15:10:47,815 PID file /opt/app/snmptrap/tmp/snmptrapd.py.pid does not exist or not readable - unable to check status of snmptrapd 2018-10-16T15:10:47,816 Diagnose further at command line as needed. @@ -82,7 +82,7 @@ Stopping trapd Output from this command will be two-fold. First will be the textual response: -.. code-block:: bash +.. code-block:: none 2018-10-16T15:10:07,808 Stopping snmptrapd PID 16109... 2018-10-16T15:10:07,810 Stopped diff --git a/docs/sections/services/snmptrap/architecture.rst b/docs/sections/services/snmptrap/architecture.rst index e65be786..88fa37c6 100644 --- a/docs/sections/services/snmptrap/architecture.rst +++ b/docs/sections/services/snmptrap/architecture.rst @@ -4,12 +4,12 @@ Architecture ============ -The ONAP **SNMPTRAP** project (referred to as **"trapd"** - as in "trap daemon" throughout +The ONAP **SNMPTRAP** project (referred to as **"trapd"** - as in "trap daemon" throughout this documentation) is a network facing ONAP platform component. The simple network management protocol (or "SNMP", for short) is a pervasive -communication protocol standard used between managed devices and a management system. -It is used to relay data that can be valuable in the operation, fault identification +communication protocol standard used between managed devices 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. SNMP utilizes a message called a "trap" to inform SNMP managers of abnormal @@ -22,10 +22,10 @@ software processes or anything else specific to the agent's environment. Capabilities ------------ -**trapd** receives SNMP traps and publishes them to a message router (DMAAP/MR) +**trapd** receives SNMP traps and publishes them to a message router (DMAAP/MR) instance based on attributes obtained from configuration binding service ("CBS"). -.. image:: ./ONAP_trapd.png +.. image:: ./ONAP_trapd.png Interactions diff --git a/docs/sections/services/snmptrap/configuration.rst b/docs/sections/services/snmptrap/configuration.rst index 5c81aafe..f421afb4 100644 --- a/docs/sections/services/snmptrap/configuration.rst +++ b/docs/sections/services/snmptrap/configuration.rst @@ -56,7 +56,7 @@ Potential Config Changes in your environment "minimum_severity_to_log": 2 # minimum message level to log; 0 recommended for debugging, 3+ recommended for runtime/production in snmpv3_config section: - + (see detailed snmpv3_config discussion below) snmpv3_config @@ -419,5 +419,5 @@ The format of the JSON configuration that drives all behavior of SNMPTRAP is pro "usmAesCfb256Protocol": "privkey47", "usmHMAC384SHA512AuthProtocol": "authkey47" } - + } diff --git a/docs/sections/services/snmptrap/delivery.rst b/docs/sections/services/snmptrap/delivery.rst index 70bdba3b..f826c57b 100644 --- a/docs/sections/services/snmptrap/delivery.rst +++ b/docs/sections/services/snmptrap/delivery.rst @@ -20,4 +20,3 @@ Standalone .. code-block:: bash gerrit.onap.org:29418/dcaegen2/collectors/snmptrap - diff --git a/docs/sections/services/snmptrap/installation.rst b/docs/sections/services/snmptrap/installation.rst index 9c549948..b733eb1c 100644 --- a/docs/sections/services/snmptrap/installation.rst +++ b/docs/sections/services/snmptrap/installation.rst @@ -7,15 +7,15 @@ Installation 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. +in a VM or on baremetal. Both scenarios are documented below. As a docker container --------------------- -**trapd** is delivered as a docker container based on python 3.6. The -host or VM that will run this container must have the docker application +**trapd** is delivered as a docker container based on python 3.6. 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. If running from a docker container, it is assumed that *Config @@ -36,12 +36,12 @@ nexus and launch it in the container named "trapd": ``docker run --detach -t --rm -p 162:6162/udp -P --name=trapd nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.snmptrap:2.0.6 ./bin/snmptrapd.sh start`` Running an instance of **trapd** will result in arriving traps being published -to the topic specified by Config Binding Services. +to the topic specified by Config Binding Services. Standalone ---------- -**trapd** can also be run outside of a container environment, without CBS interactions. +**trapd** can also be run outside of a container environment, without CBS interactions. If CBS is not present, SNMPTRAP will look for a JSON configuration file specified via the environment variable CBS_SIM_JSON at startup. Location of this file should be specified as a relative path from the <SNMPTRAP base directory>/bin directory. E.g. @@ -55,8 +55,8 @@ Prerequisites trapd requires the following to run in a non-docker environment: - Python 3.6+ - - Python module “pysnmp” 4.4.5 - - Python module “requests” 2.18.3 + - Python module "pysnmp" 4.4.5 + - Python module "requests" 2.18.3 To install prerequisites: @@ -83,7 +83,7 @@ Download a copy of the latest trapd image from gerrit in it's standard runtime l Configure for your environment """""""""""""""""""""""""""""" -In a non-docker environment, ONAP trapd is controlled by a locally hosted JSON configuration file. It is +In a non-docker environment, ONAP trapd is controlled by a locally hosted JSON configuration file. It is referenced in the trapd startup script as: .. code-block:: bash @@ -97,9 +97,9 @@ This file should be in the exact same format is the response from CBS in a fully /opt/app/snmptrap/etc/snmptrapd.json -Make applicable changes to this file - typically things that will need to change include: +Make applicable changes to this file - typically things that will need to change include: -.. code-block:: bash +.. code-block:: json "topic_url": "http://localhost:3904/events/ONAP-COLLECTOR-SNMPTRAP" @@ -115,4 +115,3 @@ Start the application """"""""""""""""""""" ``nohup /opt/app/snmptrap/bin/snmptrapd.sh start > /opt/app/snmptrap/logs/snmptrapd.out 2>&1 &`` - diff --git a/docs/sections/services/snmptrap/logging.rst b/docs/sections/services/snmptrap/logging.rst index 23c92296..089dde8c 100644 --- a/docs/sections/services/snmptrap/logging.rst +++ b/docs/sections/services/snmptrap/logging.rst @@ -26,20 +26,18 @@ Defaults are shown below: .. code-block:: json - "files": { - <other json data> - ... + {"files": { + "<other json data>": "...", "roll_frequency": "day", - "minimum_severity_to_log": 3 - <other json data> - ... - }, + "minimum_severity_to_log": 3, + "<other json data>": "..." + }} Roll Frequency """""""""""""" -Roll frequency can be modified based on your environment (e.g. if trapd is handling a +Roll frequency can be modified based on your environment (e.g. if trapd is handling a heavy trap load, you will probably want files to roll more frequently). Valid "roll_frequency" values are: - minute @@ -49,7 +47,7 @@ heavy trap load, you will probably want files to roll more frequently). Valid " Minimum Severity To Log """"""""""""""""""""""" -Logging levels should be modified based on your need. Log levels in lab environments should be "lower" +Logging levels should be modified based on your need. Log levels in lab environments should be "lower" (e.g. minimum severity to log = "0" creates verbose logging) vs. production (values of "3" and above is a good choice). Valid "minimum_severity_to_log" values are: @@ -74,7 +72,7 @@ values: .. code-block:: json - "files": { + {"files": { "runtime_base_dir": "/opt/app/snmptrap", "log_dir": "logs", "data_dir": "data", @@ -84,10 +82,9 @@ values: "traps_stats_log": "snmptrapd_stats.csv", "perm_status_file": "snmptrapd_status.log", "roll_frequency": "hour", - "minimum_severity_to_log": 2 - <other json data> - ... - }, + "minimum_severity_to_log": 2, + "<other json data>": "..." + }} The base directory for all data logs is specified with: @@ -123,8 +120,8 @@ An example from this log is shown below: 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"}] -*NOTE:* Format of this log will change with 1.5.0; specifically, "varbinds" section will be reformatted/json struct removed and will be replaced with a flat file format. - +*NOTE:* Format of this log will change with 1.5.0; specifically, "varbinds" section will be reformatted/json struct removed and will be replaced with a flat file format. + PUBLISHED TRAPS ^^^^^^^^^^^^^^^ @@ -132,7 +129,7 @@ SNMPTRAP's main purpose 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. +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 @@ -207,18 +204,17 @@ of that JSON configuration that influences EELF logging is: .. code-block:: json - "files": { - <other json data> - ... + {"files": { + "<other json data>": "...", "**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", + "roll_frequency": "hour" }, - <other json data> - ... + "<other json data>": "..." + } The base directory for all EELF logs is specified with: @@ -272,10 +268,10 @@ Messages will be in the general format of: 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.companyname.dcae.dmaap.location.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 ^^^^^^^^^^^^^^^ @@ -291,6 +287,6 @@ A permanent (left to user to archive/compress/etc) status file is maintained in Combined with **runtime_base_dir** and **log_dir** settings from snmptrapd.json, the perm_status_file in default installations can be found at: -.. code-block:: json +.. code-block:: bash /opt/app/uc/logs/snmptrapd_stats.log diff --git a/docs/sections/services/snmptrap/offeredapis.rst b/docs/sections/services/snmptrap/offeredapis.rst index fabaff5f..f5841dee 100644 --- a/docs/sections/services/snmptrap/offeredapis.rst +++ b/docs/sections/services/snmptrap/offeredapis.rst @@ -27,10 +27,10 @@ running instance. To accomplish this, you may: NetSNMP snmptrap ---------------- -One way to simulate an arriving SNMP trap is to use the Net-SNMP utility/command snmptrap. +One way to simulate an arriving SNMP trap is to use the Net-SNMP utility/command snmptrap. This command can send V1, V2c or V3 traps to a manager based on the parameters provided. -The example below sends a SNMP V1 trap to the specified host. Prior to running this command, export +The example below sends a SNMP V1 trap to the specified host. Prior to running this command, export the values of *to_ip_address* (set it to the IP of the VM hosting the ONAP trapd container) and *to_port* (typically set to "162"): @@ -52,18 +52,18 @@ python using pysnmp ------------------- Another way to simulate an arriving SNMP trap is to send one with the python *pysnmp* module. (Note that this -is the same module that ONAP trapd is based on). +is the same module that ONAP trapd is based on). -To do this, create a python script called "send_trap.py" with the following contents. You'll need to change the +To do this, create a python script called "send_trap.py" with the following contents. You'll need to change the target (from "localhost" to whatever the destination IP/hostname of the trap receiver is) before saving: .. 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)), @@ -72,7 +72,7 @@ target (from "localhost" to whatever the destination IP/hostname of the trap rec [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: @@ -80,4 +80,6 @@ target (from "localhost" to whatever the destination IP/hostname of the trap rec To run the pysnmp example: - ``python ./send_trap.py`` +.. code-block:: bash + + python ./send_trap.py diff --git a/docs/sections/services/snmptrap/release-notes.rst b/docs/sections/services/snmptrap/release-notes.rst index 98ea3d40..886c487d 100644 --- a/docs/sections/services/snmptrap/release-notes.rst +++ b/docs/sections/services/snmptrap/release-notes.rst @@ -21,11 +21,11 @@ Version: 2.3.0 **Bug Fixes** - + **Known Issues** **Security Issues** - - None + - None **Upgrade Notes** @@ -51,7 +51,7 @@ Version: 1.4.0 **Known Issues** **Security Issues** - - None + - None **Upgrade Notes** @@ -73,12 +73,12 @@ 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 + - None **Upgrade Notes** @@ -86,4 +86,3 @@ Support for config binding services. **Deprecation Notes** **Other** - |