summaryrefslogtreecommitdiffstats
path: root/docs/sections/apis
diff options
context:
space:
mode:
authorChengkai Yan <martin.c.yan@est.tech>2018-10-18 10:40:14 +0200
committerChengkai Yan <martin.c.yan@est.tech>2018-10-18 22:28:53 +0200
commit285e47c57564dbfa345cf52fffa17f67dc69e9bd (patch)
tree3ff063d106d0d368fb034a60df4bb96c29825045 /docs/sections/apis
parent2df4b8cac0edf477f4ae62ea3ea2ce8b4d3eaa20 (diff)
Update DFC documentation
Change-Id: Ifbe2df71a1bcce426b5e81c25ed39d34e439a943 Issue-ID: DCAEGEN2-642 Signed-off-by: elinuxhenrik <henrik.b.andersson@est.tech> Signed-off-by: Chengkai Yan <martin.c.yan@est.tech>
Diffstat (limited to 'docs/sections/apis')
-rw-r--r--docs/sections/apis/DFC.rst89
-rw-r--r--docs/sections/apis/DFC.yaml76
2 files changed, 162 insertions, 3 deletions
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://<container_address>:8100/heartbeat** or **https://<container_address>:8433/heartbeat**
+ - Start DFC: **http://<container_address>:8100/start** or **https://<container_address>:8433/start**
+ - Stop DFC: **http://<container_address>:8100/stopDatafile** or **https://<container_address>: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»»
+