diff options
| -rw-r--r-- | docs/sections/apis/DFC.json | 621 | ||||
| -rw-r--r-- | docs/sections/apis/DFC.rst | 187 | ||||
| -rw-r--r-- | docs/sections/services/dfc/architecture.rst | 18 | ||||
| -rw-r--r-- | docs/sections/services/dfc/certificates.rst | 115 | ||||
| -rw-r--r-- | docs/sections/services/dfc/configuration.rst | 10 | ||||
| -rw-r--r-- | docs/sections/services/dfc/consumedapis.rst | 72 | ||||
| -rw-r--r-- | docs/sections/services/dfc/index.rst | 2 |
7 files changed, 844 insertions, 181 deletions
diff --git a/docs/sections/apis/DFC.json b/docs/sections/apis/DFC.json new file mode 100644 index 00000000..08d03993 --- /dev/null +++ b/docs/sections/apis/DFC.json @@ -0,0 +1,621 @@ +{ + "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": "Heartbeat Controller" + }, + { + "name": "operation-handler", + "description": "Operation Handler" + }, + { + "name": "schedule-controller", + "description": "Schedule Controller" + }, + { + "name": "web-mvc-links-handler", + "description": "Web Mvc Links Handler" + } + ], + "paths": { + "/actuator": { + "get": { + "tags": [ + "web-mvc-links-handler" + ], + "summary": "links", + "operationId": "linksUsingGET", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/Link" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/health": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_2", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/health/{component}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_1", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/health/{component}/{instance}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/info": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_3", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/logfile": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_4", + "produces": [ + "application/octet-stream" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/loggers": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_6", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/loggers/{name}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_5", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + }, + "post": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingPOST", + "consumes": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "produces": [ + "*/*" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/metrics": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_8", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/metrics/{requiredMetricName}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_7", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/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": "Receiving 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": { + "Link": { + "type": "object", + "properties": { + "href": { + "type": "string" + }, + "templated": { + "type": "boolean" + } + }, + "title": "Link" + }, + "Map«string,Link»": { + "type": "object", + "title": "Map«string,Link»", + "additionalProperties": { + "$ref": "#/definitions/Link" + } + }, + "Mono«ResponseEntity«string»»": { + "type": "object", + "title": "Mono«ResponseEntity«string»»" + } + } +}
\ No newline at end of file diff --git a/docs/sections/apis/DFC.rst b/docs/sections/apis/DFC.rst index 57e2914c..f345d93f 100644 --- a/docs/sections/apis/DFC.rst +++ b/docs/sections/apis/DFC.rst @@ -2,7 +2,7 @@ DFC (DataFile Collector) ======================== -:Date: 2018-09-21 +:Date: 2019-04-24 .. contents:: :depth: 3 @@ -16,184 +16,11 @@ Component description can be found under `DFC`_. .. _DFC: ../../sections/services/dfc/index.html -Paths -===== +Offered APIs +============ -GET /events/unauthenticated.VES_NOTIFICATION_OUTPUT ---------------------------------------------------- +.. csv-table:: + :header: "API name", "Swagger JSON" + :widths: 10,5 -Description -~~~~~~~~~~~ - -Reads fileReady events from DMaaP (Data Movement as a Platform) - - -Responses -~~~~~~~~~ - -+-----------+---------------------+ -| HTTP Code | Description | -+===========+=====================+ -| **200** | successful response | -+-----------+---------------------+ - - - -POST /publish -------------- - -Description -~~~~~~~~~~~ - -Publish the collected file/s as a stream to DataRouter - - file as stream - - compression - - fileFormatType - - fileFormatVersion - - -Responses -~~~~~~~~~ - -+-----------+---------------------+ -| HTTP Code | Description | -+===========+=====================+ -| **200** | successful response | -+-----------+---------------------+ - -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 - -Maven GroupId: -============== - -org.onap.dcaegen2.collectors - -Maven Parent ArtifactId: -======================== - -dcae-collectors - -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: -------------------------------------------------- -.. code:: bash - - 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: ------------------------------------------------------- -.. code:: bash - - 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. - -**For TrustManager:** - -1. First, convert your certificate in a DER format : - - .. code:: bash - - openssl x509 -outform der -in ftp.crt -out ftp.der - -2. And after, import it in the keystore : - - .. code:: bash - - keytool -import -alias ftp -keystore ftp.jks -file ftp.der - -**For KeyManager:** - -1. First, create a jks keystore: - - .. code:: bash - - keytool -keystore dfc.jks -genkey -alias dfc - -2. Second, import dfc.crt and dfc.key to dfc.jks. This is a bit troublesome. - - 1). Step one: Convert x509 Cert and Key to a pkcs12 file - - .. code:: bash - - 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 yy 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. - - 2). Step two: Convert the pkcs12 file to a java keystore: - - .. code:: bash - - keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore dfc.jks -srckeystore dfc.p12 -srcstoretype PKCS12 -srcstorepass [some-password] -alias [some-alias] - -3. Finished - -4. Configure vsftpd: --------------------- - update /etc/vsftpd/vsftpd.conf: - - .. code-block:: bash - - 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: - - .. code-block:: javascript - - "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 + "Datafile Collector API", ":download:`link <DFC.json>`" diff --git a/docs/sections/services/dfc/architecture.rst b/docs/sections/services/dfc/architecture.rst index 73597541..ac0c8d14 100644 --- a/docs/sections/services/dfc/architecture.rst +++ b/docs/sections/services/dfc/architecture.rst @@ -39,4 +39,20 @@ The event is received from the Message Router (MR), the files are fetched from a (DR). Both fetching of a file and publishing is retried a number of times with an increasing delay between each attempt. After a number of attempts, the DFC will log an error message and give up. Failing of processing of one file does not -affect the handling of others.
\ No newline at end of file +affect the handling of others. + +Maven GroupId: +============== + +org.onap.dcaegen2.collectors + +Maven Parent ArtifactId: +======================== + +dcae-collectors + +Maven Children Artifacts: +========================= + +1. datafile-app-server: DFC server + diff --git a/docs/sections/services/dfc/certificates.rst b/docs/sections/services/dfc/certificates.rst new file mode 100644 index 00000000..17bfb2f3 --- /dev/null +++ b/docs/sections/services/dfc/certificates.rst @@ -0,0 +1,115 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Certificates +============ + +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: +------------------------------------------------- +.. code:: bash + + 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: +------------------------------------------------------ +.. code:: bash + + 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. + +**For TrustManager:** + +1. First, convert your certificate in a DER format : + + .. code:: bash + + openssl x509 -outform der -in ftp.crt -out ftp.der + +2. And after, import it in the keystore : + + .. code:: bash + + keytool -import -alias ftp -keystore ftp.jks -file ftp.der + +**For KeyManager:** + +1. First, create a jks keystore: + + .. code:: bash + + keytool -keystore dfc.jks -genkey -alias dfc + +2. Second, import dfc.crt and dfc.key to dfc.jks. This is a bit troublesome. + + 1). Step one: Convert x509 Cert and Key to a pkcs12 file + + .. code:: bash + + 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. + + Note 2: You might want to add the -chainoption to preserve the full certificate chain. + + 2). Step two: Convert the pkcs12 file to a java keystore: + + .. code:: bash + + keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore dfc.jks -srckeystore dfc.p12 -srcstoretype PKCS12 -srcstorepass [some-password] -alias [some-alias] + +3. Finished + +4. Configure vsftpd: +-------------------- + update /etc/vsftpd/vsftpd.conf: + + .. code-block:: bash + + 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: + + .. code-block:: javascript + + "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/services/dfc/configuration.rst b/docs/sections/services/dfc/configuration.rst index 22f50eeb..b8d0df95 100644 --- a/docs/sections/services/dfc/configuration.rst +++ b/docs/sections/services/dfc/configuration.rst @@ -7,6 +7,16 @@ Configuration **datafile** configuration is controlled via a single JSON file called datafile_endpoints.json.
This is located under datafile-app-server/config.
+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
+
+
+
JSON CONFIGURATION EXPLAINED
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/sections/services/dfc/consumedapis.rst b/docs/sections/services/dfc/consumedapis.rst new file mode 100644 index 00000000..0ab10498 --- /dev/null +++ b/docs/sections/services/dfc/consumedapis.rst @@ -0,0 +1,72 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Paths +===== + +GET /events/unauthenticated.VES_NOTIFICATION_OUTPUT +--------------------------------------------------- + +Description +~~~~~~~~~~~ + +Reads fileReady events from DMaaP (Data Movement as a Platform) + + +Responses +~~~~~~~~~ + ++-----------+---------------------+ +| HTTP Code | Description | ++===========+=====================+ +| **200** | successful response | ++-----------+---------------------+ + +GET /FEEDLOG_TOPIC/DEFAULT_FEED_ID?type=pub&filename=FILENAME +------------- + +Description +~~~~~~~~~~~ + +Querying the Data Router to check whether a file has been published previously. + +Responses +~~~~~~~~~ + ++-----------+------------+-----------------------+ +| HTTP Code | Body | Description | ++===========+============+=======================+ +| **400** | NA | error in query | ++-----------+------------+-----------------------+ +| **200** | [] | Not published yet | ++-----------+------------+-----------------------+ +| **200** | [$FILENAME]| Already published | ++-----------+------------+-----------------------+ + +POST /publish +------------- + +Description +~~~~~~~~~~~ + +Publish the collected file/s as a stream to DataRouter + - file as stream + - compression + - fileFormatType + - fileFormatVersion + - productName + - vendorName + - lastEpochMicrosec + - sourceName + - startEpochMicrosec + - timeZoneOffset + + +Responses +~~~~~~~~~ + ++-----------+---------------------+ +| HTTP Code | Description | ++===========+=====================+ +| **200** | successful response | ++-----------+---------------------+
\ No newline at end of file diff --git a/docs/sections/services/dfc/index.rst b/docs/sections/services/dfc/index.rst index 176c403c..780d63fc 100644 --- a/docs/sections/services/dfc/index.rst +++ b/docs/sections/services/dfc/index.rst @@ -14,6 +14,8 @@ DATAFILE COLLECTOR MS (DFC) ./delivery.rst
./logging.rst
./installation.rst
+ ./certificates.rst
./configuration.rst
+ ./consumedapis.rst
./administration.rst
./release-notes.rst
|