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 ### Running Locally
  21
  22 Build the image (it will go into your local docker repository)
  23 ```
  24 mvn clean package
  25 ```
  26
  27 Run the image using docker-compose.yml
  28 ```
  29 docker-compose up
  30 ```
  31
  32 ### Environment variables in Docker Container
  33 Most of the configuration of how VESCollector should be started and managed is done through environment variables.
  34 Some of them are set during the image build process and some of them are defined manually or by
  35 a particular deployment system.
  36
  37 Variables set manually / coming from deployment system:
  38 - COLLECTOR_IP
  39 - DMAAPHOST - should contain an address to DMaaP, so that event publishing can work
  40 - CBSPOLLTIMER - it should be put in here if we want to automatically fetch configuration from CBS.
  41 - CONSUL_PROTOCOL - Consul protocol by default set to **http**, if it is need to change it then that can be set to different value
  42 - CONSUL_HOST - used with conjunction with CBSPOLLTIMER, should be a host address (without port! e.g my-ip-or-host) where Consul service lies
  43 - CBS_PROTOCOL - Config Binding Service protocol by default set to **http**, if it is need to change it then that can be set to different value
  44 - CONFIG_BINDING_SERVICE - used with conjunction with CBSPOLLTIMER, should be a name of CBS as it is registered in Consul
  45 - HOSTNAME - used with conjunction with CBSPOLLTIMER, should be a name of VESCollector application as it is registered in CBS catalog
  46
  47 ### Docker file system layout
  48 The main directory where all code resides in docker container
  49 looks like this and is located in /opt/app/VESCollector
  50 ```
  51 <host>:/opt/app/VESCollector# ls
  52 Dockerfile  bin  etc  lib  logs  specs  tomcat.8080
  53 ```
  54 - bin contains sh scripts (path here is denoted by env var $SCRIPTS_PATH)
  55 - etc contains various application configuration, most notably it reflects 'etc' directory from repository
  56 - lib contains all libraries that are pulled into the app during maven build
  57 - logs contains all application logs, especially collector.log file which is a main log file denoted by $MAIN_LOG_FILE variable
  58 - specs contains json schemas specs for ves-collector
  59
  60 ## Managing application in Docker container
  61 Scripts directory contain .sh scripts that are used to start & stop & configure the VESCollector application
  62 inside the docker image.
  63 These scripts are packaged inside the docker image by a mvn assembly & docker plugins.
  64
  65 ## How the application starts inside container
  66 General flow goes like this
  67 - Docker image is build, and it points docker-entry.sh as the entrypoint.
  68 - Docker-entry point, depending on the deployment type,
  69 configures a bunch of things and starts the application in a separate process
  70 and loops indefinitely to hold the docker container process.
  71
  72 ### Release images
  73 For R1 - image/version  pushed to nexus3
  74 ```
  75 nexus3.onap.org:10003/snapshots/onap/org.onap.dcaegen2.collectors.ves.vescollector   1.1
  76 ```
  77
  78 ### Deployment
  79
  80 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.
  81
  82 For testing purpose, the docker image includes preset configuration which can be ran without DCAEGEN2 platform.
  83
  84
  85 ### Testing
  86
  87 For R1 as only measurement and faults are expected in ONAP, configuration are preset currently sto support these two topics only.
  88
  89 ```
  90 STEPS FOR SETUP/TEST
  91 1)      Get the VESCollector image from Nexus
  92                 docker pull nexus.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector:1.1
  93 2)      Start the container (change the DMAAPHOST environment value to running DMAAP instance host)
  94                 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
  95 3)      Login into container and tail /opt/app/VESCollector/logs/collector.log
  96 4)      Simulate event into VEScollector (can be done from different vm or same)
  97                 curl -i -X POST -d @measurement.txt --header "Content-Type: application/json" https://localhost:8443/eventListener/v5 -k
  98                 or curl -i  -X POST -d @measurement.txt --header "Content-Type: application/json" http://localhost:8080/eventListener/v5 -k
  99         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.
 100
 101         Any changes to property within container requires collector restart
 102         cd /opt/app/VESCollector/
 103         ./bin/appController.sh stop
 104         ./bin/appController.sh start
 105
 106 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
 107         Fault :http://<dmaaphost>:3904/events/unauthenticated.SEC_FAULT_OUTPUT
 108         Measurement : http://<dmaaphost>:3904/events/unauthenticated.SEC_MEASUREMENT_OUTPUT
 109 6)      When test is done – do ensure to remove the container (docker rm -f <containerid>) to avoid port conflict
 110 ```
 111
 112 Authentication is disabled on the container for R1; below are the steps for enabling HTTPS/authentication for VESCollector.
 113 ```
 114 1) Login to the container
 115 2) Open /opt/app/VESCollector/etc/collector.properties and edit below properties
 116                 a) Comment below property (with authentication enabled, standard http should be disabled)
 117                         collector.service.port=8080
 118                 b) Enable basic-authentication
 119                         header.authflag=1
 120      Note: The actual credentials is stored part of header.authlist parameter. This is list of userid,password (base64encoded) values. Default configuration has below set
 121                 sample1,c2FtcGxlMQ==|vdnsagg,dmRuc2FnZw==, where password maps to same value as username.
 122 3) Restart the collector
 123                 cd /opt/app/VESCollector
 124                 ./bin/appController.sh stop
 125                 ./bin/appController.sh start
 126 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.
 127 5) Simulate via curl (Note - username/pwd will be required)
 128         Example of successfull POST:
 129                 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
 130                 HTTP/1.1 200 OK
 131                 Server: Apache-Coyote/1.1
 132                 X-Rathravane: ~ software is craft ~
 133                 Content-Type: application/json;charset=ISO-8859-1
 134                 Content-Length: 17
 135                 Date: Thu, 21 Sep 2017 22:23:49 GMT
 136                 Message Accepted
 137
 138         Example of authentication failure:
 139                 vv770d@osdcae-dev-16:~$ curl -i -X POST -d @volte.txt --header "Content-Type: application/json" https://localhost:8443/eventListener/v5 -k
 140                 HTTP/1.1 401 Unauthorized
 141                 Server: Apache-Coyote/1.1
 142                 X-Rathravane: ~ software is craft ~
 143                 Content-Type: application/json;charset=ISO-8859-1
 144                 Content-Length: 96
 145                 Date: Thu, 21 Sep 2017 22:20:43 GMT
 146                 Connection: close
 147                 {"requestError":{"GeneralException":{"MessagID":"\"POL2000\"","text":"\"Unauthorized user\""}}}
 148
 149 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.
 150 ```
 151
 152 A client's certificate verification is disabled on the container by default; below are the steps for enabling mutual TLS authentication for VESCollector.
 153 ```
 154 1) Login to the container
 155 2) Open /opt/app/VESCollector/etc/collector.properties and edit below properties
 156                 a) Comment below property (with authentication enabled, standard http should be disabled)
 157                         collector.service.port=8080
 158                 b) Enable a client's certificate verification
 159                         collector.service.secure.clientauth=1
 160 3) Restart the collector
 161                 cd /opt/app/VESCollector
 162                 ./bin/appController.sh stop
 163                 ./bin/appController.sh start
 164 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.
 165 5) In order for VESCollector to accept a connection from a client, the client has to use TLS certificate signed by CA that is present in VESCollector truststore. If a default VESCollector truststore is used then a client's certificate may be generated using following steps:
 166                 a) Generate a client's private key
 167                     openssl genrsa -out client.key 2048
 168                 b) Create the signing
 169                     openssl req -new -key client.key -out client.csr
 170                 c) Create the client's certificate (CA key password should be obtained from [VESCollectorRepository]/certs/password)
 171                     openssl x509 -req -in client.csr -CA [VESCollectorRepository]/certs/rootCA.crt -CAkey [VESCollectorRepository]/certs/rootCA.key -CAcreateserial -out client.crt -days 500 -sha256
 172 6) Simulate via curl (assuming that the certificate was created via step 5)
 173     Example of successfull POST:
 174         curl -i -X POST -d @event.json --header "Content-Type: application/json" https://localhost:8443/eventListener/v7 -k --cert client.crt --key client.key
 175         HTTP/1.1 100
 176
 177         HTTP/1.1 202
 178         Content-Type: application/json
 179         Content-Length: 8
 180         Date: Wed, 21 Nov 2018 11:37:58 GMT
 181
 182     Example of authentication failure (without a client's certificate):
 183         curl -i -X POST -d @event.json --header "Content-Type: application/json" https://localhost:8443/eventListener/v7 -k
 184         curl: (35) error:14094412:SSL routines:ssl3_read_bytes:sslv3 alert bad certificate