docs/sections/apis/DFC.rst

   1 ==============================
   2 DFC (DataFile Collector)
   3 ==============================
   4
   5 :Date: 2018-09-21
   6
   7 .. contents::
   8     :depth: 3
   9 ..
  10
  11 Overview
  12 ========
  13
  14 DFC will orchestrate the collection of bulk PM data flow:
  15     1. Subscribes to fileReady DMaaP topic
  16     2. Collects the file from the xNF
  17     3. Sends new event to DataRouter with file.
  18
  19 Introduction
  20 ============
  21
  22 DFC is delivered as one **Docker container** which hosts application server and can be started by `docker-compose`.
  23
  24 Functionality
  25 =============
  26 .. image:: ../images/DFC.png
  27
  28
  29 Paths
  30 =====
  31
  32 GET /events/unauthenticated.VES_NOTIFICATION_OUTPUT
  33 -----------------------------------------------
  34
  35 Description
  36 ~~~~~~~~~~~
  37
  38 Reads fileReady events from DMaaP (Data Movement as a Platform)
  39
  40
  41 Responses
  42 ~~~~~~~~~
  43
  44 +-----------+-------------------------------------------+
  45 | HTTP Code | Description                               |
  46 +===========+===========================================+
  47 | **200**   | successful response                       |
  48 +-----------+-------------------------------------------+
  49
  50
  51
  52 POST /publish
  53 --------------------------------------
  54
  55 Description
  56 ~~~~~~~~~~~
  57
  58 Publish the collected file/s as a stream to DataRouter
  59     - file as stream
  60     - compression
  61     - fileFormatType
  62     - fileFormatVersion
  63
  64
  65 Responses
  66 ~~~~~~~~~
  67
  68 +-----------+-------------------------------------------+
  69 | HTTP Code | Description                               |
  70 +===========+===========================================+
  71 | **200**   | successful response                       |
  72 +-----------+-------------------------------------------+
  73
  74 Compiling DFC
  75 =============
  76
  77 Whole project (top level of DFC directory) and each module (sub module directory) can be compiled using
  78 `mvn clean install` command.
  79
  80 Configuration file: Config/datafile_endpoints.json
  81
  82 Main API Endpoints
  83 ==================
  84
  85 Running with dev-mode of DFC
  86     - Heartbeat: **http://<container_address>:8100/heartbeat** or **https://<container_address>:8433/heartbeat**
  87     - Start DFC: **http://<container_address>:8100/start** or **https://<container_address>:8433/start**
  88     - Stop DFC: **http://<container_address>:8100/stopDatafile** or **https://<container_address>:8433/stopDatafile**
  89
  90 The external port allocated for 8100 (http) is 30245.
  91
  92 Maven GroupId:
  93 ==============
  94
  95 org.onap.dcaegen2.collectors
  96
  97 Maven Parent ArtifactId:
  98 ========================
  99
 100 dcae-collectors
 101
 102 Maven Children Artifacts:
 103 =========================
 104
 105 1. datafile-app-server: DFC server
 106 2. datafile-dmaap-client: Contains implementation of DmaaP client
 107 3. datafile-commons: Common code for whole DFC modules
 108 4. docker-compose: Contains the docker-compose
 109
 110 Configuration of Certificates in test environment(For FTP over TLS):
 111 ====================================================================
 112 DFC supports two protocols: FTPES and SFTP.
 113 For FTPES, it is mutual authentication with certificates.
 114 In our test environment, we use vsftpd to simulate xNF, and we generate self-signed
 115 keys & certificates on both vsftpd server and DFC.
 116 1. generate key & certificate with openssl for DFC：
 117     openssl genrsa -out dfc.key 2048
 118     openssl req -new -out dfc.csr -key dfc.key
 119     openssl x509 -req -days 365 -in dfc.csr -signkey dfc.key -out dfc.crt
 120 2. generate key & certificate with openssl for vsftpd:
 121     openssl genrsa -out ftp.key 2048
 122     openssl req -new -out ftp.csr -key ftp.key
 123     openssl x509 -req -days 365 -in ftp.csr -signkey ftp.key -out ftp.crt
 124 3. configure java keystore in DFC:
 125     We have two keystore files, one for TrustManager, one for KeyManager.
 126     First, create a jks keystore for TrustManager:
 127       keytool -keystore ftp.jks -genkey -alias ftp
 128     Second, convert your certificate in a DER format :
 129       openssl x509 -outform der -in ftp.crt -out ftp.der
 130     And after, import it in the keystore :
 131       keytool -import -alias ftp -keystore ftp.jks -file ftp.der
 132
 133     For KeyManager:
 134     First, create a jks keystore:
 135       keytool -keystore dfc.jks -genkey -alias dfc
 136     Second, import dfc.crt and dfc.key to dfc.jks. This is a bit troublesome.
 137       Step one: Convert x509 Cert and Key to a pkcs12 file
 138       openssl pkcs12 -export -in dfc.crt -inkey dfc.key \
 139                -out dfc.p12 -name [some-alias] \
 140       Note: Make sure you put a password on the p12 file - otherwise you'll get
 141       a null reference exception when you try to import it. (In case anyone else had this headache).
 142       Note 2: You might want to add the -chainoption to preserve the full certificate chain.
 143       Step two: Convert the pkcs12 file to a java keystore
 144       keytool -importkeystore \
 145         -deststorepass [changeit] -destkeypass [changeit] -destkeystore dfc.jks \
 146         -srckeystore dfc.p12 -srcstoretype PKCS12 -srcstorepass some-password \
 147         -alias [some-alias]
 148     Finished
 149
 150 4. configure vsftpd:
 151     update /etc/vsftpd/vsftpd.conf:
 152       rsa_cert_file=/etc/ssl/private/ftp.crt
 153       rsa_private_key_file=/etc/ssl/private/ftp.key
 154       ssl_enable=YES
 155       allow_anon_ssl=NO
 156       force_local_data_ssl=YES
 157       force_local_logins_ssl=YES
 158
 159       ssl_tlsv1=YES
 160       ssl_sslv2=YES
 161       ssl_sslv3=YES
 162
 163       require_ssl_reuse=NO
 164       ssl_ciphers=HIGH
 165
 166       require_cert=YES
 167       ssl_request_cert=YES
 168       ca_certs_file=/home/vsftpd/myuser/dfc.crt
 169
 170 5. configure config/datafile_endpoints.json:
 171    Update the file accordingly:
 172             "ftpesConfiguration": {
 173                 "keyCert": "/config/dfc.jks",
 174                 "keyPassword": "[yourpassword]",
 175                 "trustedCA": "/config/ftp.jks",
 176                 "trustedCAPassword": "[yourpassword]"
 177             }
 178 6. This has been tested with vsftpd and dfc, with self-signed certificates.
 179    In real deployment, we should use ONAP-CA signed certificate for DFC, and vendor-CA signed
 180    certificate for xNF.