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 VES Collector is a Spring Boot application
  22 ```
  23 mvn spring-boot:run
  24
  25 ```
  26
  27 Build the image (it will go into your local docker repository)
  28 ```
  29 mvn clean package
  30
  31 ```
  32 Run the image using docker
  33 ```
  34 docker run -p 8080:8080 -p 8443:8443 <container_id>
  35 ```
  36
  37 Run the image using docker-compose.yml
  38 ```
  39 docker-compose up
  40 ```
  41
  42 ### Generate auth credential
  43
  44 Library to generate new cryptographic password is stored in dcaegen2/sdk -"security/crypt-password"
  45
  46 or download artifact from:
  47
  48 https://nexus.onap.org/#nexus-search;quick~crypt-password
  49
  50 How to use:
  51 ```
  52 java -jar crypt-password-<version>.jar password_to_crypt
  53 ```
  54
  55 ### Mechanism to validate Certificate Subject DN value
  56 When application is in certOnly or certBasicAuth mode then certificates are also validated by regexp in certSubjectMatcher.properties, only SubjectDn field in certificate description are checked.
  57 Default regexp value is .* means that we approve all SubjectDN values.
  58
  59 ### Environment variables in Docker Container
  60 Most of the configuration of how VESCollector should be started and managed is done through environment variables.
  61 Some of them are set during the image build process and some of them are defined manually or by
  62 a particular deployment system.
  63
  64 Variables set manually / coming from deployment system:
  65 - COLLECTOR_IP
  66 - DMAAPHOST - should contain an address to DMaaP, so that event publishing can work
  67 - CONFIG_BINDING_SERVICE - should be a name of CBS
  68 - CONFIG_BINDING_SERVICE_SERVICE_PORT - should be an http port of CBS
  69 - HOSTNAME - should be a name of VESCollector application as it is registered in CBS catalog
  70
  71 ### Docker file system layout
  72 The main directory where all code resides in docker container
  73 looks like this and is located in /opt/app/VESCollector
  74 ```
  75 <host>:/opt/app/VESCollector# ls
  76 Dockerfile  bin  etc  lib  logs  specs
  77 ```
  78 - bin contains sh scripts (path here is denoted by env var $SCRIPTS_PATH)
  79 - etc contains various application configuration, most notably it reflects 'etc' directory from repository
  80 - lib contains all libraries that are pulled into the app during maven build
  81 - logs contains all application logs, especially collector.log file which is a main log file denoted by $MAIN_LOG_FILE variable
  82 - specs contains json schemas specs for ves-collector
  83
  84 ## Managing application in Docker container
  85 Scripts directory contain .sh scripts that are used to start & stop & configure the VESCollector application
  86 inside the docker image.
  87 These scripts are packaged inside the docker image by a mvn assembly & docker plugins.
  88
  89 ## How the application starts inside container
  90 General flow goes like this
  91 - Docker image is build, and it points docker-entry.sh as the entrypoint.
  92 - Docker-entry point, depending on the deployment type,
  93 configures a bunch of things and starts the application in a separate process
  94 and loops indefinitely to hold the docker container process.
  95
  96 ### Release images
  97 For R1 - image/version  pushed to nexus3
  98 ```
  99 nexus3.onap.org:10003/snapshots/onap/org.onap.dcaegen2.collectors.ves.vescollector:<version>
 100 ```
 101
 102 ### Deployment
 103
 104 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.
 105
 106 For testing purpose, the docker image includes preset configuration which can be ran without DCAEGEN2 platform.
 107
 108
 109
 110 ### Consul - Dynamic configuration
 111
 112
 113 Application properties like /etc/collector.properties and Dmaap configuration /etc/DmaapConfig.json are updated frequently by configuration stored in Consul(CBS)
 114 http://<kubernetes_host_ip>:30270/ui/#/dc1/kv/<vescollector_SCN>
 115 Configuration stored in Consul have bigger priority and always will override local configuration so all configuration modification should be done using Consul update on corresponding kv store.
 116 Frequently how often configuration will be fetch from Consul server is manageable in /etc/collector.properties property "collector.dynamic.config.update.frequency={time in minutes}".
 117 To fetch configuration from Consul, VES collector uses CBS client from DCAE SDK.
 118
 119 Sample configuration of VESCollector K-V store can be found under /dpo/data-formats/ConsulConfig.json
 120
 121
 122 ### Testing
 123
 124 For R1 as only measurement and faults are expected in ONAP, configuration are preset currently sto support these two topics only.
 125
 126 ```
 127 STEPS FOR SETUP/TEST
 128 1)      Get the VESCollector image from Nexus
 129                 docker pull nexus.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector:latest
 130 2)      Start the container (change the DMAAPHOST environment value to running DMAAP instance host)
 131                 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
 132 3)      Login into container and tail /opt/app/VESCollector/logs/collector.log
 133 4)      Simulate event into VEScollector (can be done from different vm or same)
 134                 curl -i -X POST -d @measurement.txt --header "Content-Type: application/json" https://localhost:8443/eventListener/v5 -k
 135                 or curl -i  -X POST -d @measurement.txt --header "Content-Type: application/json" http://localhost:8080/eventListener/v5 -k
 136         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.
 137
 138         Any changes to property within container requires collector restart
 139         cd /opt/app/VESCollector/
 140         ./bin/appController.sh stop
 141         ./bin/appController.sh start
 142
 143 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
 144         Fault :http://<dmaaphost>:3904/events/unauthenticated.SEC_FAULT_OUTPUT
 145         Measurement : http://<dmaaphost>:3904/events/unauthenticated.SEC_MEASUREMENT_OUTPUT
 146 6)      When test is done – do ensure to remove the container (docker rm -f <containerid>) to avoid port conflict
 147 ```
 148
 149 Authentication is set by default to "noauth" (via auth.method property) on the container; below are the steps for enabling HTTPS/authentication for VESCollector.
 150 ```
 151 1) Login to the container
 152 2) Open /opt/app/VESCollector/etc/collector.properties and edit below properties
 153                 a) Comment below property (with authentication enabled, standard http should be disabled)
 154                         collector.service.port=8080
 155                 b) Enable basic-authentication
 156                   auth.method=basicAuth
 157      Note: The actual credentials is stored part of header.authlist parameter. This is list of userid,password values. Default configuration has below set
 158                 sample1,$2a$10$pgjaxDzSuc6XVFEeqvxQ5u90DKJnM/u7TJTcinAlFJVaavXMWf/Zi|vdnsagg,$2a$10$C45JhiRSY.qXTBfzWST3Q.AmwKlPRMc67c33O0U9hOH8KSGaweN4m
 159                 where password maps to same value as username.
 160                 Password is generated by crypt-password tool (https://nexus.onap.org/#nexus-search;quick~crypt-password)
 161 3) Restart the collector
 162                 cd /opt/app/VESCollector
 163                 ./bin/appController.sh stop
 164                 ./bin/appController.sh start
 165 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.
 166 5) Simulate via curl (Note - username/pwd will be required)
 167     Example of successfull POST:
 168                 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
 169                 HTTP/1.1 200 OK
 170                 Server: Apache-Coyote/1.1
 171                 X-Rathravane: ~ software is craft ~
 172                 Content-Type: application/json;charset=ISO-8859-1
 173                 Content-Length: 17
 174                 Date: Thu, 21 Sep 2017 22:23:49 GMT
 175                 Message Accepted
 176
 177         Example of authentication failure:
 178                 vv770d@osdcae-dev-16:~$ curl -i -X POST -d @volte.txt --header "Content-Type: application/json" https://localhost:8443/eventListener/v5 -k
 179                 HTTP/1.1 401 Unauthorized
 180                 Server: Apache-Coyote/1.1
 181                 X-Rathravane: ~ software is craft ~
 182                 Content-Type: application/json;charset=ISO-8859-1
 183                 Content-Length: 96
 184                 Date: Thu, 21 Sep 2017 22:20:43 GMT
 185                 Connection: close
 186                 {"requestError":{"GeneralException":{"MessagID":"\"POL2000\"","text":"\"Unauthorized user\""}}}
 187
 188 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.
 189 ```
 190
 191 A client's certificate verification is disabled on the container by default; below are the steps for enabling mutual TLS authentication for VESCollector.
 192 ```
 193 1) Login to the container
 194 2) Open /opt/app/VESCollector/etc/collector.properties and edit below properties
 195                 a) Comment below property (with authentication enabled, standard http should be disabled)
 196                         collector.service.port=8080
 197                 b) Enable a client's certificate verification
 198                   auth.method=certOnly (only certificate verification)
 199                         or
 200                         auth.method=certBasicAuth ( certificate verification with basic auth verification )
 201 3) Restart the collector
 202                 cd /opt/app/VESCollector
 203                 ./bin/appController.sh stop
 204                 ./bin/appController.sh start
 205 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.
 206 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:
 207                 a) Generate a client's private key
 208                     openssl genrsa -out client.key 2048
 209                 b) Create the signing
 210                     openssl req -new -key client.key -out client.csr
 211                 c) Create the client's certificate (CA key password should be obtained from [VESCollectorRepository]/certs/password)
 212                     openssl x509 -req -in client.csr -CA [VESCollectorRepository]/certs/rootCA.crt -CAkey [VESCollectorRepository]/certs/rootCA.key -CAcreateserial -out client.crt -days 500 -sha256
 213 6) Simulate via curl (assuming that the certificate was created via step 5)
 214     Example of successfull POST:
 215         curl -i -X POST -d @event.json --header "Content-Type: application/json" https://localhost:8443/eventListener/v7 -k --cert client.crt --key client.key
 216         HTTP/1.1 100
 217
 218         HTTP/1.1 202
 219         Content-Type: application/json
 220         Content-Length: 8
 221         Date: Wed, 21 Nov 2018 11:37:58 GMT
 222
 223     Example of authentication failure (without a client's certificate):
 224         curl -i -X POST -d @event.json --header "Content-Type: application/json" https://localhost:8443/eventListener/v7 -k
 225         curl: (35) error:14094412:SSL routines:ssl3_read_bytes:sslv3 alert bad certificate