diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/sections/services/snmptrap/ONAP_trapd.png | bin | 0 -> 36575 bytes | |||
| -rw-r--r-- | docs/sections/services/snmptrap/administration.rst | 95 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/architecture.rst | 64 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/configuration.rst | 387 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/delivery.rst | 19 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/humaninterfaces.rst | 6 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/installation.rst | 122 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/logging.rst | 73 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/offeredapis.rst | 45 | ||||
| -rw-r--r-- | docs/sections/services/snmptrap/release-notes.rst | 33 |
10 files changed, 670 insertions, 174 deletions
diff --git a/docs/sections/services/snmptrap/ONAP_trapd.png b/docs/sections/services/snmptrap/ONAP_trapd.png Binary files differnew file mode 100644 index 00000000..53b7ffaa --- /dev/null +++ b/docs/sections/services/snmptrap/ONAP_trapd.png diff --git a/docs/sections/services/snmptrap/administration.rst b/docs/sections/services/snmptrap/administration.rst index 950badac..ab5ec6e2 100644 --- a/docs/sections/services/snmptrap/administration.rst +++ b/docs/sections/services/snmptrap/administration.rst @@ -7,39 +7,106 @@ Administration Processes --------- -**SNMPTRAP** runs as a single (python) process inside the container. You can find it using the following commands: +**trapd** runs as a single (python) process inside (or outside) the container. You can monitor it using the commands documented below. + +*NOTE:* Familiarity with docker environments is assumed below - for example, if you stop a running instance of snmptrapd that was started using the default snmptrapd docker configuration, the container itself will exit. Similarly, if you start an instance of snmptrapd inside a container, it will not run in the background (this is a dependency/relationship between docker and the application -> if the command registered to run the service inside the container terminates, it is assumed that the application has failed and docker will terminate the container itself). + +Actions +------- + +Starting snmptrapd +^^^^^^^^^^^^^^^^^^ + +The **trapd** service can be started by running the command: + + ``/opt/app/snmptrap/bin/snmptrapd.sh start`` + +Output from this command will be two-fold. First will be the textual response: -Inside the container -^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash - `ps -ef | grep snmptrap.py | grep -v grep` + 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 + 2018-10-16T19:15:01,966 ONAP controller override specified via CBS_SIM_JSON: ../etc/snmptrapd.json + 2018-10-16T19:15:01,973 ../etc/snmptrapd.json loaded and parsed successfully + 2018-10-16T19:15:02,038 load_all_configs|snmptrapd||||INFO|100||current config logged to : /opt/app/snmptrap/tmp/current_config.json + 2018-10-16T19:15:02,048 snmptrapd.py : ONAP SNMP Trap Receiver version 1.4.0 starting + 2018-10-16T19:15:02,049 arriving traps logged to: /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log + 2018-10-16T19:15:02,050 published traps logged to: /opt/app/snmptrap/logs/DMAAP_unauthenticated.ONAP-COLLECTOR-SNMPTRAP.json + +*NOTE:* This command will remain in the foreground for reasons explained above. + +Checking Status +^^^^^^^^^^^^^^^ + +The **trapd** container can be monitored for status by running this command from inside the container: + ``/opt/app/snmptrap/bin/snmptrapd.sh status`` -Outside the container -^^^^^^^^^^^^^^^^^^^^^ +If **SNMPTRAPD** is present/running, output from this command will be: .. code-block:: bash - docker exec -it <container name> `ps -ef | grep snmptrap.py | grep -v grep` + 2018-10-16T15:01:47,705 Status: snmptrapd running + ucsnmp 16109 16090 0 Oct08 ? 00:07:16 python ./snmptrapd.py +and the return code presented to the shell upon exit: -Actions -------- + 0 -> if command executed successfully and the process was found + 1 -> if the command failed, and/or the process is not running + + ``$ echo $?`` + + ``0`` -The **SNMPTRAP** container can be monitored for status by running the command: +If **trapd** is not present, output from this command will be: .. code-block:: bash - `bin/snmptrapd.sh status` + 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. + +and the return code presented to the shell upon exit: + + ``$ echo $?`` + + ``1`` + + +Stopping trapd +^^^^^^^^^^^^^^ + +**trapd** can be stopped by running the command: + + ``/opt/app/snmptrap/bin/snmptrapd.sh stop`` Output from this command will be two-fold. First will be the textual response: - `Stopping snmptrap... Stopped.` +.. code-block:: bash + + 2018-10-16T15:10:07,808 Stopping snmptrapd PID 16109... + 2018-10-16T15:10:07,810 Stopped -Also available is the return code of the command: +Second will be the return code presented to the shell upon exit: 0 - if command executed successfully - 1 - if the command failed, and/or the process is not running + 1 - if the request to stop failed + + ``$ echo $?`` + + ``0`` + + +Other commands of interest +-------------------------- + +Checking for snmptrapd inside a container +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + ``ps -ef | grep snmptrap.py | grep -v grep`` + +Checking for snmptrapd outside the container +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ``docker exec -it <container name> ps -ef | grep snmptrap.py | grep -v grep`` diff --git a/docs/sections/services/snmptrap/architecture.rst b/docs/sections/services/snmptrap/architecture.rst index 7f51f5f4..e65be786 100644 --- a/docs/sections/services/snmptrap/architecture.rst +++ b/docs/sections/services/snmptrap/architecture.rst @@ -4,16 +4,13 @@ Architecture ============ -**SNMPTRAP** (or "trapd", as in trap daemon) is a network facing ONAP platform -component. +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 -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. +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 +and planning processes of all networks. 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 @@ -25,44 +22,15 @@ 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; - } +**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 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. @@ -71,14 +39,8 @@ subscribed to the topic they were published to. Usage Scenarios --------------- -**SNMPTRAP** runs in a docker container based on python 3.6. Running -an instance of **SNMPTRAP** will result in arriving traps being published +**trapd** runs in a docker container based on python 3.6. Running +an instance of **trapd** 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 variable CBS_SIM_JSON at startup. Note that relative paths -will be located from the bin (<SNMPTRAP base directory>/bin directory. E.g. - -.. code-block:: bash - - CBS_SIM_JSON=../etc/snmptrapd.json - +SNMPTRAP will look for a JSON configuration file specified via the +environment variable CBS_SIM_JSON at startup (see "CONFIGURATION" link for details). diff --git a/docs/sections/services/snmptrap/configuration.rst b/docs/sections/services/snmptrap/configuration.rst index 2c8afe23..44a23d93 100644 --- a/docs/sections/services/snmptrap/configuration.rst +++ b/docs/sections/services/snmptrap/configuration.rst @@ -4,37 +4,115 @@ Configuration ============= -**SNMPTRAP** configuration is controlled via a single JSON 'transaction'. +**trapd** configuration is controlled via a single JSON 'transaction'. This transaction can be: - - a reply from config binding services - - - a locally hosted JSON file +- a reply from Config Binding Services +- a locally hosted JSON file The format of this message is described in the SNMPTRAP package, under: - ``<base install dir>/spec/snmptrap-collector-component-spec.json`` +.. code-block:: bash + + <base install dir>/spec/snmptrap-collector-component-spec.json + +There will also be a template JSON file with example/default values found at: -There should also be a template JSON file with example/default values found at: +.. code-block:: bash - ``<base install dir>/etc/snmptrapd.json`` + <base install dir>/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`` +.. code-block:: bash + + 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 CONFIGURATION EXPLAINED +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Variables of interest (e.g. variables that should be inspected/modifed for a specific runtime environment) are listed below for convenience. The entire file is provided later in this page for reference. + +Potential Config Changes in your environment +"""""""""""""""""""""""""""""""""""""""""""" + +.. code-block:: bash + + in protocols section: + + "ipv4_interface": "0.0.0.0", # IPv4 address of interface to listen on - "0.0.0.0" == "all" + "ipv4_port": 6162, # UDP port to listen for IPv4 traps on (6162 used in docker environments when forwarding has been enabled) + "ipv6_interface": "::1", # IPv6 address of interface to listen on - "::1" == "all" + "ipv6_port": 6162 # UDP port to listen for IPv6 traps on (6162 used in docker environments when forwarding has been enabled) + + in cache section: + + "dns_cache_ttl_seconds": 60 # number of seconds trapd will cache IP-to-DNS-name values before checking for update + + in files section: + + "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 +""""""""""""" + +SNMPv3 added significant authorization and privacy capabilities to the SNMP standard. As it relates to traps, this means providing the proper privacy, authorization, engine and user criteria for each agent that would like to send traps to a particular trapd instance. + +This is done by adding blocks of valid configuration data to the "snmpv3_config" section of the JSON config/transaction. These blocks are recurring sets of: -In either scenario, the format of the config message/transaction is the same. An example is described below. +.. code-block:: json + + { + "user": "<userId>", + "engineId": "<engineId>", + "<authProtocol>": "<authorizationKeyValue>", + "<privProtocol>": "<privacyKeyValue>" + } + +Valid values for authProtocol in JSON configuration: + +.. code-block:: bash + + usmHMACMD5AuthProtocol + usmHMACSHAAuthProtocol + usmHMAC128SHA224AuthProtocol + usmHMAC192SHA256AuthProtocol + usmHMAC256SHA384AuthProtocol + usmHMAC384SHA512AuthProtocol + usmNoAuthProtocol + +Valid values for privProtocol in JSON configuration: + +.. code-block:: bash + + usm3DESEDEPrivProtocol + usmAesCfb128Protocol + usmAesCfb192Protocol + usmAesBlumenthalCfb192Protocol + usmAesCfb256Protocol + usmAesBlumenthalCfb256Protocol + usmDESPrivProtocol + usmNoPrivProtocol -JSON CONFIG -^^^^^^^^^^^ +User and engineId values are left up to the administrator, and must conform to SNMPv3 specifications as explained at `https://tools.ietf.org/html/rfc3414` . -The format of the JSON configuration that drives all behavior of SNMPTRAP is probably best described using an example. One can be found below: + +Sample JSON configuration +""""""""""""""""""""""""" + +The format of the JSON configuration that drives all behavior of SNMPTRAP is probably best described using an example: .. code-block:: json { "snmptrapd": { - "version": "1.3.0", + "version": "1.4.0", "title": "ONAP SNMP Trap Receiver" }, "protocols": { @@ -43,6 +121,7 @@ The format of the JSON configuration that drives all behavior of SNMPTRAP is pro "ipv4_port": 6162, "ipv6_interface": "::1", "ipv6_port": 6162 + }, "cache": { "dns_cache_ttl_seconds": 60 @@ -84,31 +163,261 @@ The format of the JSON configuration that drives all behavior of SNMPTRAP is pro "eelf_audit": "audit.log", "eelf_metrics": "metrics.log", "roll_frequency": "hour", - "minimum_severity_to_log": 2 + "minimum_severity_to_log": 3 }, - "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" + "snmpv3_config": { + "usm_users": [ + { + "engineId": "8000000000000001", + "user": "user1", + "usmDESPrivProtocol": "privkey1", + "usmHMACMD5AuthProtocol": "authkey1" + }, + { + "engineId": "8000000000000002", + "user": "user2", + "usm3DESEDEPrivProtocol": "privkey2", + "usmHMACMD5AuthProtocol": "authkey2" + }, + { + "engineId": "8000000000000003", + "user": "user3", + "usmAesCfb128Protocol": "privkey3", + "usmHMACMD5AuthProtocol": "authkey3" + }, + { + "engineId": "8000000000000004", + "user": "user4", + "usmAesBlumenthalCfb192Protocol": "privkey4", + "usmHMACMD5AuthProtocol": "authkey4" + }, + { + "engineId": "8000000000000005", + "user": "user5", + "usmAesBlumenthalCfb256Protocol": "privkey5", + "usmHMACMD5AuthProtocol": "authkey5" + }, + { + "engineId": "8000000000000006", + "user": "user6", + "usmAesCfb192Protocol": "privkey6", + "usmHMACMD5AuthProtocol": "authkey6" + }, + { + "engineId": "8000000000000007", + "user": "user7", + "usmAesCfb256Protocol": "privkey7", + "usmHMACMD5AuthProtocol": "authkey7" + }, + { + "engineId": "8000000000000009", + "user": "user9", + "usmDESPrivProtocol": "privkey9", + "usmHMACSHAAuthProtocol": "authkey9" + }, + { + "engineId": "8000000000000010", + "user": "user10", + "usm3DESEDEPrivProtocol": "privkey10", + "usmHMACSHAAuthProtocol": "authkey10" + }, + { + "engineId": "8000000000000011", + "user": "user11", + "usmAesCfb128Protocol": "privkey11", + "usmHMACSHAAuthProtocol": "authkey11" + }, + { + "engineId": "8000000000000012", + "user": "user12", + "usmAesBlumenthalCfb192Protocol": "privkey12", + "usmHMACSHAAuthProtocol": "authkey12" + }, + { + "engineId": "8000000000000013", + "user": "user13", + "usmAesBlumenthalCfb256Protocol": "privkey13", + "usmHMACSHAAuthProtocol": "authkey13" + }, + { + "engineId": "8000000000000014", + "user": "user14", + "usmAesCfb192Protocol": "privkey14", + "usmHMACSHAAuthProtocol": "authkey14" + }, + { + "engineId": "8000000000000015", + "user": "user15", + "usmAesCfb256Protocol": "privkey15", + "usmHMACSHAAuthProtocol": "authkey15" + }, + { + "engineId": "8000000000000017", + "user": "user17", + "usmDESPrivProtocol": "privkey17", + "usmHMAC128SHA224AuthProtocol": "authkey17" + }, + { + "engineId": "8000000000000018", + "user": "user18", + "usm3DESEDEPrivProtocol": "privkey18", + "usmHMAC128SHA224AuthProtocol": "authkey18" + }, + { + "engineId": "8000000000000019", + "user": "user19", + "usmAesCfb128Protocol": "privkey19", + "usmHMAC128SHA224AuthProtocol": "authkey19" + }, + { + "engineId": "8000000000000020", + "user": "user20", + "usmAesBlumenthalCfb192Protocol": "privkey20", + "usmHMAC128SHA224AuthProtocol": "authkey20" + }, + { + "engineId": "8000000000000021", + "user": "user21", + "usmAesBlumenthalCfb256Protocol": "privkey21", + "usmHMAC128SHA224AuthProtocol": "authkey21" + }, + { + "engineId": "8000000000000022", + "user": "user22", + "usmAesCfb192Protocol": "privkey22", + "usmHMAC128SHA224AuthProtocol": "authkey22" + }, + { + "engineId": "8000000000000023", + "user": "user23", + "usmAesCfb256Protocol": "privkey23", + "usmHMAC128SHA224AuthProtocol": "authkey23" + }, + { + "engineId": "8000000000000025", + "user": "user25", + "usmDESPrivProtocol": "privkey25", + "usmHMAC192SHA256AuthProtocol": "authkey25" + }, + { + "engineId": "8000000000000026", + "user": "user26", + "usm3DESEDEPrivProtocol": "privkey26", + "usmHMAC192SHA256AuthProtocol": "authkey26" + }, + { + "engineId": "8000000000000027", + "user": "user27", + "usmAesCfb128Protocol": "privkey27", + "usmHMAC192SHA256AuthProtocol": "authkey27" + }, + { + "engineId": "8000000000000028", + "user": "user28", + "usmAesBlumenthalCfb192Protocol": "privkey28", + "usmHMAC192SHA256AuthProtocol": "authkey28" + }, + { + "engineId": "8000000000000029", + "user": "user29", + "usmAesBlumenthalCfb256Protocol": "privkey29", + "usmHMAC192SHA256AuthProtocol": "authkey29" + }, + { + "engineId": "8000000000000030", + "user": "user30", + "usmAesCfb192Protocol": "privkey30", + "usmHMAC192SHA256AuthProtocol": "authkey30" + }, + { + "engineId": "8000000000000031", + "user": "user31", + "usmAesCfb256Protocol": "privkey31", + "usmHMAC192SHA256AuthProtocol": "authkey31" + }, + { + "engineId": "8000000000000033", + "user": "user33", + "usmDESPrivProtocol": "privkey33", + "usmHMAC256SHA384AuthProtocol": "authkey33" + }, + { + "engineId": "8000000000000034", + "user": "user34", + "usm3DESEDEPrivProtocol": "privkey34", + "usmHMAC256SHA384AuthProtocol": "authkey34" + }, + { + "engineId": "8000000000000035", + "user": "user35", + "usmAesCfb128Protocol": "privkey35", + "usmHMAC256SHA384AuthProtocol": "authkey35" + }, + { + "engineId": "8000000000000036", + "user": "user36", + "usmAesBlumenthalCfb192Protocol": "privkey36", + "usmHMAC256SHA384AuthProtocol": "authkey36" + }, + { + "engineId": "8000000000000037", + "user": "user37", + "usmAesBlumenthalCfb256Protocol": "privkey37", + "usmHMAC256SHA384AuthProtocol": "authkey37" + }, + { + "engineId": "8000000000000038", + "user": "user38", + "usmAesCfb192Protocol": "privkey38", + "usmHMAC256SHA384AuthProtocol": "authkey38" + }, + { + "engineId": "8000000000000039", + "user": "user39", + "usmAesCfb256Protocol": "privkey39", + "usmHMAC256SHA384AuthProtocol": "authkey39" + }, + { + "engineId": "8000000000000041", + "user": "user41", + "usmDESPrivProtocol": "privkey41", + "usmHMAC384SHA512AuthProtocol": "authkey41" + }, + { + "engineId": "8000000000000042", + "user": "user42", + "usm3DESEDEPrivProtocol": "privkey42", + "usmHMAC384SHA512AuthProtocol": "authkey42" + }, + { + "engineId": "8000000000000043", + "user": "user43", + "usmAesCfb128Protocol": "privkey43", + "usmHMAC384SHA512AuthProtocol": "authkey43" + }, + { + "engineId": "8000000000000044", + "user": "user44", + "usmAesBlumenthalCfb192Protocol": "privkey44", + "usmHMAC384SHA512AuthProtocol": "authkey44" + }, + { + "engineId": "8000000000000045", + "user": "user45", + "usmAesBlumenthalCfb256Protocol": "privkey45", + "usmHMAC384SHA512AuthProtocol": "authkey45" + }, + { + "engineId": "8000000000000046", + "user": "user46", + "usmAesCfb192Protocol": "privkey46", + "usmHMAC384SHA512AuthProtocol": "authkey46" + }, + { + "engineId": "8000000000000047", + "user": "user47", + "usmAesCfb256Protocol": "privkey47", + "usmHMAC384SHA512AuthProtocol": "authkey47" } - } - } - } + + } diff --git a/docs/sections/services/snmptrap/delivery.rst b/docs/sections/services/snmptrap/delivery.rst index fe861b0b..87425582 100644 --- a/docs/sections/services/snmptrap/delivery.rst +++ b/docs/sections/services/snmptrap/delivery.rst @@ -4,15 +4,20 @@ 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. +Docker Container +---------------- -The following command will download the latest SNMPTRAP container from -nexus and launch it in the container named "SNMPTRAP": +**trapd** is delivered as a docker container that can be downloaded from onap: -.. 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`` + + +Standalone +---------- - 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 +**trapd** can also be run outside of a docker environment (for details, see "Installation" link) by downloading the source image from: + +.. code-block:: bash + gerrit.onap.org:29418/dcaegen2/collectors/snmptrap diff --git a/docs/sections/services/snmptrap/humaninterfaces.rst b/docs/sections/services/snmptrap/humaninterfaces.rst index 53f8adcd..8cd1ba3b 100644 --- a/docs/sections/services/snmptrap/humaninterfaces.rst +++ b/docs/sections/services/snmptrap/humaninterfaces.rst @@ -13,7 +13,7 @@ Command Line ^^^^^^^^^^^^ There is a command line interface available, which is a shell script -that provides all needed interactions with **SNMPTRAP**. +that provides all needed interactions with **trapd**. Usage """"" @@ -24,8 +24,8 @@ Usage stop - terminate the snmptrapd process currently running inside container - restart - start an instance of snmptrapd inside current container + restart - restart an instance of snmptrapd inside current container (NOTE: this may cause container to exit depending on how it was started!) status - check and display status of snmptrapd inside container - reloadCfg - signal current instance of snmptrapd to re-request configuration from Config Binding Service + reloadCfg - signal current instance of snmptrapd to re-request configuration from Config Binding Service (NOTE: Known issue for configurations that include SNMPv3 credentials, this option will not work as expected) diff --git a/docs/sections/services/snmptrap/installation.rst b/docs/sections/services/snmptrap/installation.rst index 3fbb4cde..d91a46b3 100644 --- a/docs/sections/services/snmptrap/installation.rst +++ b/docs/sections/services/snmptrap/installation.rst @@ -4,36 +4,114 @@ 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. +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 +loaded and available to the userID that will be running the SNMPTRAP container. + +If running from a docker container, it is assumed that *Config +Binding Service* has been installed and is successfully providing valid +configuration assets to instantiated containers as needed. + +Also required is a working DMAAP/MR environment. trapd +publishes traps to DMAAP/MR as JSON messages and expects the host +resources and publishing credentials to be included in the *Config Binding Service* +config. + +Installation +^^^^^^^^^^^^ + +The following command will download the latest trapd container from +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 ./bin/snmptrapd.sh start`` + +Running an instance of **trapd** will result in arriving traps being published +to the topic specified by Config Binding Services. + +Standalone +---------- + +**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. + +Installation +^^^^^^^^^^^^ + +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 + +To install prerequisites: + + ``export PATH=<path to Python 3.6 binary>:$PATH`` + + ``pip3 install requests==2.18.3`` -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. + ``pip3 install pysnmp==4.4.5`` -Steps ------ +Download latest trapd version from Gerrit +""""""""""""""""""""""""""""""""""""""""" -The following command will download the latest snmptrap container -from nexus and launch it in the container named "snmptrap": +Download a copy of the latest trapd image from gerrit in it's standard runtime location: + + ``cd /opt/app`` + + ``git clone ssh://<your linux foundation id>@gerrit.onap.org:29418/dcaegen2/collectors/snmptrap snmptrap`` + +"Un-dockerize" +"""""""""""""" + + ``mv /opt/app/snmptrap/snmptrap /opt/app/snmptrap/bin`` + +Configure for your environment +"""""""""""""""""""""""""""""" + +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 + + CBS_SIM_JSON=../etc/snmptrapd.json + + +This file should be in the exact same format is the response from CBS in a fully implemented container/controller environment. A sample file is included with source/container images, at: .. 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 + /opt/app/snmptrap/etc/snmptrapd.json + +Make applicable changes to this file - typically things that will need to change include: + +.. code-block:: bash + + "topic_url": "http://localhost:3904/events/ONAP-COLLECTOR-SNMPTRAP" + +Action: Change 'localhost' and topic name (ONAP-COLLECTOR-SNMPTRAP) to desired values in your environment. + +.. code-block:: bash + + "snmpv3_config" (needed only when SNMPv3 agents are present) + +Action: Add/delete/modify entries as needed to align with SNMP agent configurations in a SNMPv3 environment. + +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 a7109a00..23c92296 100644 --- a/docs/sections/services/snmptrap/logging.rst +++ b/docs/sections/services/snmptrap/logging.rst @@ -4,9 +4,9 @@ Logging ======= -Logging is controlled by the configuration provided to **SNMPTRAP** by CBS, +Logging is controlled by the configuration provided to **trapd** by CBS, or via the fallback config file specified as the environment -variable "CBS_SIM_JSON" at startup. The section of that JSON configuration +variable "CBS_SIM_JSON" at startup. The section of the JSON configuration that influences the various forms of application logging is referenced throughout this document, with examples. @@ -17,8 +17,7 @@ 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 +severity level to log to program diagnostic logs. 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). @@ -30,20 +29,45 @@ Defaults are shown below: "files": { <other json data> ... - "roll_frequency": "hour", - "minimum_severity_to_log": 2 + "roll_frequency": "day", + "minimum_severity_to_log": 3 <other json data> ... }, -Where to Access Information: APPLICATION DATA (TRAPS) ------------------------------------------------------ +Roll Frequency +"""""""""""""" + +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 +- hour +- day + +Minimum Severity To Log +""""""""""""""""""""""" + +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: + +- "1" (debug mode - everything you want to know about process, and more. *NOTE:* Not recommended for production environments) +- "2" (info - verbose logging. *NOTE:* Not recommended for production environments) +- "3" (warnings - functionality not impacted, but abnormal/uncommon event) +- "4" (critical - functionality impacted, but remains running) +- "5" (fatal - causing runtime exit) + -APPLICATION DATA (TRAPS) -^^^^^^^^^^^^^^^^^^^^^^^^ +WHERE ARE THE LOG FILES? +------------------------ + +APPLICATION DATA +^^^^^^^^^^^^^^^^ -**SNMPTRAP** produces application-specific logs (e.g. trap logs/payloads, +**trapd** 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: @@ -51,7 +75,7 @@ values: .. code-block:: json "files": { - "**runtime_base_dir**": "/opt/app/snmptrap", + "runtime_base_dir": "/opt/app/snmptrap", "log_dir": "logs", "data_dir": "data", "pid_dir": "tmp", @@ -84,7 +108,7 @@ above example would create the files: ARRIVING TRAPS ^^^^^^^^^^^^^^^ -**SNMPTRAP** logs all arriving traps. These traps are saved in a +**trapd** 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: @@ -99,12 +123,12 @@ 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"}] -*(Add: varbind type enumerations)* +*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 ^^^^^^^^^^^^^^^ -SNMPTRAP's first priority is to receive and decode SNMP traps, then +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 @@ -132,7 +156,7 @@ and "files": { "**runtime_base_dir**": "/opt/app/snmptrap", -result in traps that are confirmed (200/ok) as published logged to the file: +result in traps that are confirmed as published (200/ok response from DMAAP/MR) logged to the file: .. code-block:: bash @@ -170,14 +194,14 @@ An example from this JSON log is shown below: EELF ^^^^ -For program/operational logging, **SNMPTRAP** follows the EELF logging +For program/operational logging, **trapd** 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 +to **trapd** 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: @@ -249,13 +273,24 @@ Messages will be in the general format of: 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,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 ^^^^^^^^^^^^^^^ +A permanent (left to user to archive/compress/etc) status file is maintained in the file referenced by: + + **perm_status_file** + .. code-block:: json "perm_status_file": "snmptrapd_status.log", + +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 + + /opt/app/uc/logs/snmptrapd_stats.log diff --git a/docs/sections/services/snmptrap/offeredapis.rst b/docs/sections/services/snmptrap/offeredapis.rst index e9a8afeb..48b40d11 100644 --- a/docs/sections/services/snmptrap/offeredapis.rst +++ b/docs/sections/services/snmptrap/offeredapis.rst @@ -4,11 +4,11 @@ Offered APIs ============ -**SNMPTRAP** supports the Simple Network Management Protocol (SNMP) +**trapd** 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 +As an API offering, the only way to interact with **trapd** 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: @@ -18,17 +18,28 @@ running instance. To accomplish this, you may: 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 +2. Simulate 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. + environment.* -Net-SNMP --------- +NetSNMP snmptrap +---------------- -.. code-block:: bash +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. - 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" +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"): + + ``export to_ip_address=192.168.1.1`` + + ``export to_port=162`` + +Then run the Net-SNMP command/utility: + + ``snmptrap -d -v 1 -c not_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:: @@ -36,8 +47,14 @@ Net-SNMP they can be ignored, the trap has successfully been sent to the specified destination. -pysnmp ------- +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). + +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 @@ -58,4 +75,8 @@ pysnmp if errorIndication: print(errorIndication) else: - print("successfully sent first trap example, number %d" % i) + print("successfully sent trap") + +To run the pysnmp example: + + ``python ./send_trap.py`` diff --git a/docs/sections/services/snmptrap/release-notes.rst b/docs/sections/services/snmptrap/release-notes.rst index 45a0f152..ec031323 100644 --- a/docs/sections/services/snmptrap/release-notes.rst +++ b/docs/sections/services/snmptrap/release-notes.rst @@ -5,18 +5,37 @@ 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.4.0 +-------------- + +:Release Date: 2018-10-01 + +**New Features** + + - `https://jira.onap.org/browse/DCAEGEN2-630` + Added support for SNMPv3 traps with varying levels of privacy and authentication support. + +**Bug Fixes** + - `https://jira.onap.org/browse/DCAEGEN2-842` + Remove additional RFC3584 (Sec 3.1 (4)) varbinds from published/logged SNMPv1 messages, fix DMAAP publish error for traps with no varbinds present. + +**Known Issues** + +**Security Issues** + - None + +**Upgrade Notes** + +**Deprecation Notes** + +**Other** + +=========== Version: 1.3.0 -------------- - :Release Date: 2018-05-02 |
