Merge "Update DFC documentation"

4 files changed, 163 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»»
+
diff --git a/docs/sections/images/DFC.png b/docs/sections/images/DFC.png
index 216f5947..dc607691 100644
--- a/docs/sections/images/DFC.png
+++ b/docs/sections/images/DFC.png
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