From 285e47c57564dbfa345cf52fffa17f67dc69e9bd Mon Sep 17 00:00:00 2001 From: Chengkai Yan Date: Thu, 18 Oct 2018 10:40:14 +0200 Subject: Update DFC documentation Change-Id: Ifbe2df71a1bcce426b5e81c25ed39d34e439a943 Issue-ID: DCAEGEN2-642 Signed-off-by: elinuxhenrik Signed-off-by: Chengkai Yan --- docs/sections/apis/DFC.rst | 89 ++++++++++++++++++++++++++++++++++++++++-- docs/sections/apis/DFC.yaml | 76 ++++++++++++++++++++++++++++++++++++ docs/sections/images/DFC.png | Bin 43468 -> 145553 bytes docs/sections/offeredapis.rst | 1 + 4 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 docs/sections/apis/DFC.yaml (limited to 'docs/sections') diff --git a/docs/sections/apis/DFC.rst b/docs/sections/apis/DFC.rst index 0605f3fa..7bf73856 100644 --- a/docs/sections/apis/DFC.rst +++ b/docs/sections/apis/DFC.rst @@ -23,7 +23,7 @@ DFC is delivered as one **Docker container** which hosts application server and Functionality ============= -../images/DFC.png +.. image:: ../images/DFC.png Paths @@ -77,6 +77,18 @@ Compiling DFC Whole project (top level of DFC directory) and each module (sub module directory) can be compiled using `mvn clean install` command. +Configuration file: Config/datafile_endpoints.json + +Main API Endpoints +================== + +Running with dev-mode of DFC + - Heartbeat: **http://:8100/heartbeat** or **https://:8433/heartbeat** + - Start DFC: **http://:8100/start** or **https://:8433/start** + - Stop DFC: **http://:8100/stopDatafile** or **https://:8433/stopDatafile** + +The external port allocated for 8100 (http) is 30245. + Maven GroupId: ============== @@ -93,5 +105,76 @@ Maven Children Artifacts: 1. datafile-app-server: DFC server 2. datafile-dmaap-client: Contains implementation of DmaaP client 3. datafile-commons: Common code for whole DFC modules - - +4. docker-compose: Contains the docker-compose + +Configuration of Certificates in test environment(For FTP over TLS): +==================================================================== +DFC supports two protocols: FTPES and SFTP. +For FTPES, it is mutual authentication with certificates. +In our test environment, we use vsftpd to simulate xNF, and we generate self-signed +keys & certificates on both vsftpd server and DFC. +1. generate key & certificate with openssl for DFC： + openssl genrsa -out dfc.key 2048 + openssl req -new -out dfc.csr -key dfc.key + openssl x509 -req -days 365 -in dfc.csr -signkey dfc.key -out dfc.crt +2. generate key & certificate with openssl for vsftpd: + openssl genrsa -out ftp.key 2048 + openssl req -new -out ftp.csr -key ftp.key + openssl x509 -req -days 365 -in ftp.csr -signkey ftp.key -out ftp.crt +3. configure java keystore in DFC: + We have two keystore files, one for TrustManager, one for KeyManager. + First, create a jks keystore for TrustManager: + keytool -keystore ftp.jks -genkey -alias ftp + Second, convert your certificate in a DER format : + openssl x509 -outform der -in ftp.crt -out ftp.der + And after, import it in the keystore : + keytool -import -alias ftp -keystore ftp.jks -file ftp.der + + For KeyManager: + First, create a jks keystore: + keytool -keystore dfc.jks -genkey -alias dfc + Second, import dfc.crt and dfc.key to dfc.jks. This is a bit troublesome. + Step one: Convert x509 Cert and Key to a pkcs12 file + openssl pkcs12 -export -in dfc.crt -inkey dfc.key \ + -out dfc.p12 -name [some-alias] \ + Note: Make sure you put a password on the p12 file - otherwise you'll get + a null reference exception when you try to import it. (In case anyone else had this headache). + Note 2: You might want to add the -chainoption to preserve the full certificate chain. + Step two: Convert the pkcs12 file to a java keystore + keytool -importkeystore \ + -deststorepass [changeit] -destkeypass [changeit] -destkeystore dfc.jks \ + -srckeystore dfc.p12 -srcstoretype PKCS12 -srcstorepass some-password \ + -alias [some-alias] + Finished + +4. configure vsftpd: + update /etc/vsftpd/vsftpd.conf: + rsa_cert_file=/etc/ssl/private/ftp.crt + rsa_private_key_file=/etc/ssl/private/ftp.key + ssl_enable=YES + allow_anon_ssl=NO + force_local_data_ssl=YES + force_local_logins_ssl=YES + + ssl_tlsv1=YES + ssl_sslv2=YES + ssl_sslv3=YES + + require_ssl_reuse=NO + ssl_ciphers=HIGH + + require_cert=YES + ssl_request_cert=YES + ca_certs_file=/home/vsftpd/myuser/dfc.crt + +5. configure config/datafile_endpoints.json: + Update the file accordingly: + "ftpesConfiguration": { + "keyCert": "/config/dfc.jks", + "keyPassword": "[yourpassword]", + "trustedCA": "/config/ftp.jks", + "trustedCAPassword": "[yourpassword]" + } +6. This has been tested with vsftpd and dfc, with self-signed certificates. + In real deployment, we should use ONAP-CA signed certificate for DFC, and vendor-CA signed + certificate for xNF. diff --git a/docs/sections/apis/DFC.yaml b/docs/sections/apis/DFC.yaml new file mode 100644 index 00000000..7f56ca55 --- /dev/null +++ b/docs/sections/apis/DFC.yaml @@ -0,0 +1,76 @@ +--- +swagger: '2.0' +info: + description: This page lists all the rest apis for DATAFILE app server. + version: '1.0' + title: DATAFILE app server +host: localhost:8100 +basePath: "/" +tags: +- name: heartbeat-controller + description: Check liveness of DATAFILE service +- name: schedule-controller + description: Schedule Controller +paths: + "/heartbeat": + get: + tags: + - heartbeat-controller + summary: Returns liveness of DATAFILE service + operationId: heartbeatUsingGET + produces: + - "*/*" + responses: + '200': + description: DATAFILE service is living + schema: + "$ref": "#/definitions/Mono«ResponseEntity«string»»" + '401': + description: You are not authorized to view the resource + '403': + description: Accessing the resource you were trying to reach is forbidden + '404': + description: The resource you were trying to reach is not found + "/start": + get: + tags: + - schedule-controller + summary: Start scheduling worker request + operationId: startTasksUsingGET + produces: + - "*/*" + responses: + '200': + description: OK + schema: + "$ref": "#/definitions/Mono«ResponseEntity«string»»" + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Not Found + "/stopDatafile": + get: + tags: + - schedule-controller + summary: Stop scheduling worker request + operationId: stopTaskUsingGET + produces: + - "*/*" + responses: + '200': + description: OK + schema: + "$ref": "#/definitions/Mono«ResponseEntity«string»»" + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Not Found +definitions: + Mono«ResponseEntity«string»»: + type: object + title: Mono«ResponseEntity«string»» + diff --git a/docs/sections/images/DFC.png b/docs/sections/images/DFC.png index 216f5947..dc607691 100644 Binary files a/docs/sections/images/DFC.png and b/docs/sections/images/DFC.png differ diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst index c5c652eb..fc9cb773 100644 --- a/docs/sections/offeredapis.rst +++ b/docs/sections/offeredapis.rst @@ -12,5 +12,6 @@ DCAEGEN2 Components Offered APIs apis/ves-hv/index.rst apis/dcaecdap.rst apis/PRH.rst + apis/DFC.rst -- cgit 1.2.3-korg