README.md

   1 DCAE VESCollector
   2 ======================================
   3
   4 This is the repository for VES Collector for Open DCAE.
   5
   6 Virtual Event Streaming (VES) Collector is RESTful collector for processing JSON messages into DCAE. The collector verifies the source (when authentication is enabled) and validates the events against VES schema before distributing to DMAAP MR topics for downstream system to subscribe. The VESCollector also provides configurable event transformation function and event distribution to DMAAP MR topics.
   7
   8 The collector supports individual events or eventbatch posted to collector end-point(s) and post them to interface/bus for other application to subscribe.
   9
  10
  11 ### Build Instructions
  12
  13 This project is organized as a mvn project and has "org.onap.dcaegen2" as parent project. The build generate a jar and package into docker container.
  14
  15 ```
  16 git clone ssh://vv770d@gerrit.onap.org:29418/dcaegen2/collectors/ves
  17 mvn clean install
  18 ```
  19
  20 ### Docker Image
  21
  22 ```
  23 git clone ssh://vv770d@gerrit.onap.org:29418/dcaegen2/collectors/ves
  24 mvn clean deploy
  25 ```
  26
  27 For R1 - image/version  pushed to nexus3
  28 ```
  29 nexus3.onap.org:10003/snapshots/onap/org.onap.dcaegen2.collectors.ves.vescollector   1.1
  30 ```
  31
  32 ### Deployment
  33
  34 VESCollector in DCAE will be deployed as mS via DCAEGEN2 controller. A blueprint will be generated (CLAMP/SDC) which will fetch the docker image and install on the dockerhost identified. VESCollector on startup will query the configbindingService for updated configuration and starts the service. When configuration change is detected by DCAEGEN2 controller (via policy flow) - then contoller will notify Collector to fetch new configuration again.
  35
  36 For testing purpose, the docker image includes preset configuration which can be ran without DCAEGEN2 platform.
  37
  38
  39 ### Testing
  40
  41 For R1 as only measurement and faults are expected in ONAP, configuration are preset currently sto support these two topics only.
  42
  43 ```
  44 STEPS FOR SETUP/TEST
  45 1)      Get the VESCollector image from Nexus
  46                 docker pull nexus.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector:1.1
  47 2)      Start the container (change the DMAAPHOST environment value to running DMAAP instance host)
  48                 docker run -d -p 8080:8080/tcp -p 8443:8443/tcp -P -e DMAAPHOST='10.0.0.174' nexus.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector:1.1
  49 3)      Login into container and tail /opt/app/VESCollector/logs/collector.log
  50 4)      Simulate event into VEScollector (can be done from different vm or same)
  51                 curl -i -X POST -d @measurement.txt --header "Content-Type: application/json" https://localhost:8443/eventListener/v5 -k
  52                 or curl -i  -X POST -d @measurement.txt --header "Content-Type: application/json" http://localhost:8080/eventListener/v5 -k
  53         Note: If DMAAPHOST provided is invalid, you will see exception around publish on the collector.logs (collector queues and attempts to resend the event hence exceptions reported will be periodic).   If you don’t want to see the error, publish to dmaap can be disabled by changing either “collector.dmaap.streamid” on etc/collector.properties OR by modifying the “name” defined on  etc/DmaapConfig.json.
  54
  55         Any changes to property within container requires collector restart
  56         /opt/app/VESCollector/bin/VESrestfulCollector.sh stop
  57         /opt/app/VESCollector/bin/VESrestfulCollector.sh start
  58
  59 5)      If DMAAP instance (and DMAAPHOST passed during VESCollector startup) and VES input is valid, then events will be pushed to below topics depending on the domain
  60         Fault :http://<dmaaphost>:3904/events/unauthenticated.SEC_FAULT_OUTPUT
  61         Measurement : http://<dmaaphost>:3904/events/unauthenticated.SEC_MEASUREMENT_OUTPUT
  62 6)      When test is done – do ensure to remove the container (docker rm -f <containerid>) to avoid port conflict
  63 ```
  64
  65 Authentication is disabled on the container for R1; below are the steps for enabling HTTPS/authentication for VESCollector.
  66 ```
  67 1) Login to the container
  68 2) Open /opt/app/VESCollector/etc/collector.properties and edit below properties
  69                 a) Comment below property (with authentication enabled, standard http should be disabled)
  70                         collector.service.port=8080
  71                 b) Enable basic-authentication
  72                         header.authflag=1
  73      Note: The actual credentials is stored part of header.authlist parameter. This is list of userid,password (base64encoded) values. Default configuration has below set
  74                 sample1,c2FtcGxlMQ==|vdnsagg,dmRuc2FnZw==, where password maps to same value as username.
  75 3) Restart the collector
  76                 cd /opt/app/VESCollector/bin
  77                 ./VESrestfulCollector.sh stop
  78                 ./VESrestfulCollector.sh start
  79 4) Exit from container and ensure tcp port on VM is not hanging on finwait – you can execute “netstat -an | grep 8443” . If under FIN_WAIT2, wait for server to release.
  80 5) Simulate via curl (Note - username/pwd will be required)
  81         Example of successfull POST:
  82                 vv770d@osdcae-dev-16:~$ curl -i  -u 'sample1:sample1' -X POST -d @volte.txt --header "Content-Type: application/json" https://localhost:8443/eventListener/v5 -k
  83                 HTTP/1.1 200 OK
  84                 Server: Apache-Coyote/1.1
  85                 X-Rathravane: ~ software is craft ~
  86                 Content-Type: application/json;charset=ISO-8859-1
  87                 Content-Length: 17
  88                 Date: Thu, 21 Sep 2017 22:23:49 GMT
  89                 Message Accepted
  90
  91         Example of authentication failure:
  92                 vv770d@osdcae-dev-16:~$ curl -i -X POST -d @volte.txt --header "Content-Type: application/json" https://localhost:8443/eventListener/v5 -k
  93                 HTTP/1.1 401 Unauthorized
  94                 Server: Apache-Coyote/1.1
  95                 X-Rathravane: ~ software is craft ~
  96                 Content-Type: application/json;charset=ISO-8859-1
  97                 Content-Length: 96
  98                 Date: Thu, 21 Sep 2017 22:20:43 GMT
  99                 Connection: close
 100                 {"requestError":{"GeneralException":{"MessagID":"\"POL2000\"","text":"\"Unauthorized user\""}}}
 101
 102 Note: In general support for HTTPS also require certificate/keystore be installed on target VM with FS mapped into the container for VESCollector to load. For demo and testing purpose - a self signed certificate is included within docker build. When deployed via DCAEGEN2 platform - these configuration will be overridden dynamically to map to required path/certificate name. This will be exercised post R1 though.
 103 ```