Merge "documentation for using guard in the PDP"

6 files changed, 206 insertions, 42 deletions

diff --git a/docs/platform/architecture.rst b/docs/platform/architecture.rst
index d9ce3c8cb..28215dedc 100644
--- a/docs/platform/architecture.rst
+++ b/docs/platform/architecture.rst
@@ -96,3 +96,5 @@ Attributes can be specified for each dimension. In addition to being defined for
 Policy writers can define attributes so that policy events or requests self-indicate their scope. The scope is then examined by a suitable function and subsequently acted upon accordingly. Policy decisions and enforcement functions can self-indicate their scope of decision-making, enforcement, or other capabilities. Virtual functions can be automatically attached to the appropriate POLICY Framework and distribution mechanisms.
 
 
+End of Document
+
diff --git a/docs/platform/deployPDPPAP.rst b/docs/platform/deployPDPPAP.rst
index 2c9b77575..476d6860b 100644
--- a/docs/platform/deployPDPPAP.rst
+++ b/docs/platform/deployPDPPAP.rst
@@ -17,69 +17,71 @@ Accessing and Starting PAP
 
 - To access the PAP docker use 
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    docker exec -it -u 0 pap su - policy
+        docker exec -it -u 0 pap su - policy
 
 - All Policy related software are installed under the policy account, the policy root directory is under *${POLICY_HOME}* environment variable and it may be changed on a per installation basis. It is typically set up under the */opt/app/policy* directory but can be changed during installation. All Policy software runs with non-root privileges as *policy* is a regular user account. 
 
 - Once within the PAP Container the running status can be checked using the following policy status command.
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    policy [--debug] status|start|stop
+        policy [--debug] status|start|stop
 
 - To get the current status of Policy use *policy.sh status*
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    policy@pap:~$ policy.sh status
-        pap: UP: running with pid 2114
-        console: UP: running with pid 2135
-        paplp: UP: running with pid 2155
-        3 cron jobs installed.
+        policy@pap:~$ policy.sh status
+            pap: UP: running with pid 2114
+            console: UP: running with pid 2135
+            paplp: UP: running with pid 2155
+            3 cron jobs installed.
 
 - To Stop the components use *policy.sh stop*
 
-.. code-block:: bash
-
-    policy@pap:~$ policy.sh stop
-        paplp: STOPPING ..
-        console: STOPPING ..
-        pap: STOPPING ..
+    .. code-block:: bash
+    
+        policy@pap:~$ policy.sh stop
+            paplp: STOPPING ..
+            console: STOPPING ..
+            pap: STOPPING ..
 
 - To Start use *policy.sh start* 
 
-.. code-block:: bash
-
-    policy@pap:~$ policy.sh start
-        pap: STARTING ..
-        console: STARTING ..
-        paplp: STARTING ..
+    .. code-block:: bash
+    
+        policy@pap:~$ policy.sh start
+            pap: STARTING ..
+            console: STARTING ..
+            paplp: STARTING ..
 
 Healthcheck
 -----------
 
 - To perform Health check on policy components you can follow the generic procedure documented as below. 
 
-.. code-block:: bash
-
-    # Assuming the healthcheck service credentials have not been changed
-    # post-installation within the drools container
-
-    source /opt/policy/config/drools/feature-healthcheck.conf
-
-    curl --silent --user "${HEALTHCHECK_USER}:${HEALTHCHECK_PASSWORD}" 
-                   -X GET http://localhost:6969/healthcheck | python -m json.tool
+    .. code-block:: bash
+    
+        # Assuming the healthcheck service credentials have not been changed
+        # post-installation within the drools container
+    
+        source /opt/policy/config/drools/feature-healthcheck.conf
+    
+        curl --silent --user "${HEALTHCHECK_USER}:${HEALTHCHECK_PASSWORD}" 
+                       -X GET http://localhost:6969/healthcheck | python -m json.tool
 
 - Additional information can be found in the documentation for Testing, Deploying, and debugging on a PDP-D Healthcheck. 
 
 Logs
 ----
 
-- Logs for PAP are located at *$POLICY_HOME/servers/pap/logs/* location. The main application logs can be found at *$POLICY_HOME/servers/pap/logs/Policy/ONAP-PAP-REST* location. 
-- Policy PAP uses EELF logging framework for logging and if needed to be modified can be modified at *$POLICY_HOME/servers/pap/webapps/pap/WEB-INF/classes/logback.xml*. This change needs a restart of the PAP component in order to be in effect. 
-- The Logs are divided into separate files and debug logs can be found in *debug.log* and error logs in *error.log* file which are two different files under application logs directory. 
+- Logs for PAP are located at *$POLICY_HOME/servers/pap/logs/* location. The main application logs can be found at *$POLICY_HOME/servers/pap/logs/Policy/ONAP-PAP-REST* location.   
+
+* Policy PAP uses EELF logging framework for logging and if needed to be modified can be modified at *$POLICY_HOME/servers/pap/webapps/pap/WEB-INF/classes/logback.xml*.  This change needs a restart of the PAP component in order to be in effect.  
+
+- The Logs are divided into separate files and debug logs can be found in *debug.log* and error logs in *error.log* file which are two different files under application logs directory.   
 
 PDP (Policy Decision Point)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
@@ -89,21 +91,23 @@ Accessing and Starting PDP
 
 - To access the PDP docker : 
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    docker exec -it -u 0 pdp su - policy
+        docker exec -it -u 0 pdp su - policy
 
 - To start and stop the PDP components the same procedure can be followed as documented for PAP. 
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    policy [--debug] status|start|stop
+        policy [--debug] status|start|stop
 
 Healthcheck / Testing
 ---------------------
 
 - The Policy PDP health check can be checked using the generic procedure documented above for PAP which applies to all policy components. 
-- Apart from the above check PDP also provides the swagger UI from which PDP REST APIs which can be tested and used, this also lets us know the PDP Status. In order to access PDP's swagger UI visit http://{PDP_URL}:8081/pdp/swagger-ui.html 
+
+* Apart from the above check PDP also provides the swagger UI from which PDP REST APIs which can be tested and used, this also lets us know the PDP Status. In order to access PDP's swagger UI visit http://{PDP_URL}:8081/pdp/swagger-ui.html 
+
 - In order to test the Policy components, the swagger UI provided by PDP can be used to test PDP and PAP. 
 
 
diff --git a/docs/platform/guardpdp.rst b/docs/platform/guardpdp.rst
new file mode 100644
index 000000000..f53357bbd
--- /dev/null
+++ b/docs/platform/guardpdp.rst
@@ -0,0 +1,153 @@
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+************************
+Using guard in the PDP-D 
+************************
+
+.. contents::
+    :depth: 3
+
+This guide will help configure and test guard connection from PDP-D to PDP-X. This guide assumes that the PDP-D is installed and running policy properly with other properties being set properly.
+
+Configuration
+^^^^^^^^^^^^^ 
+
+Prerequisites
+-------------
+
+Stop Policy, open, and verify the config:
+
+- Stop policy with *policy stop*
+- Open *$POLICY_HOME/config/controlloop.properties.environment*
+- Make sure the *sql.db.host*, *sql.db.username* and *sql.db.password* are set correctly
+
+
+Guard Properties
+----------------
+
+**guard.url** - URL endpoint of the PDP-X which will receive the request.
+    - For example, *http://pdp:8081/pdp/api/getDecision* will connect to the localhost PDP-X.
+    - This request requires some configuration for PDP-X properties below.
+    - For testing this URL before running policy, see Verification below.
+
+**guard.jdbc.url** - URL of the database location to which the operations history will be written.
+    - For example, *mariadb://mariadb:3306/onap_sdk*.
+    - Note that the port is included.
+    - Note that at the end, the database name is used.
+
+**guard.disabled** - For enabling / disabling guard functionality.
+    - For example, to enable set it to false.
+    - When this is set to true, the previous two properties will be ignored.
+    - If guard is enabled, then the following PDP-X properties must also be set.
+
+
+PDP-X Properties
+----------------
+
+For testing these properties before running policy, see Verification below.
+
+**pdpx.host** - URL of the PDP-X
+    - For example, pdp can be used when PDP-X is on localhost.
+
+**pdpx.username** - User to authenticate
+
+**pdpx.password** - User Password
+
+**pdpx.environment** - Environment making requests
+    - For example, TEST
+
+**pdpx.client.username** - Client to authenticate
+
+**pdpx.client.password** - Client password
+
+
+
+Verification
+^^^^^^^^^^^^ 
+
+It is recommended to test using CLI tools before running since changing bash command parameters are faster than restarting policy.
+
+Logs Verification
+-----------------
+Checking the logs is straight forward. Check the *$POLICY_HOME/logs/error.log* file for the word "*callRESTfulPDP*" for any exceptions thrown. If they are thrown then there was a problem with the connection.
+You can also check the *$POLICY_HOME/logs/network.log* file for the word "*Indeterminate*" which implies the connection failed or got a non 200 response code.
+
+CLI Verification
+----------------
+
+It can be helpful to test the PDP-X connection using bash commands to make sure that the PDP-X properties are correct and the guard.url property is correct before running policy.
+
+**Method 1: httpie - CLI, cURL-like tool for humans**
+    
+    Using the http command we can make a request directly to PDP-X from the command line. Use the following form:
+
+    .. code-block:: bash
+    
+        http
+         POST pdp:8081/pdp/api/getDecision
+         Authorization:<yourAuth> ClientAuth:<yourClientAuth>
+         Environment:<environment> Content-Type:application/json < guard_request.json
+    
+    | where:
+    |     *<yourAuth>*       is the string generated from user:pass converted to base64 encoding 
+    |                        (a conversion tool is available at https://www.base64encode.org/)
+    |     *<yourClientAuth>* is generated the same way but from the client user and pass.
+    |     *<environment>*    is the context of the request. For example: TEST
+    |     *pdp*              is the host of the PDP-X
+    
+
+    The guard_request.json should be in the form of the following:
+    
+    .. code-block:: json
+       :caption: guard_request.json
+    
+        {
+          "decisionAttributes": {
+                "actor": "APPC",
+                "recipe": "Restart",
+                "target": "test13",
+                "clname" : "piptest"
+            },
+          "onapName": "PDPD"
+        }
+
+    * This request uses Basic Access Authentication.  
+    * This request will need further configuration if you are using a proxy.
+
+    
+    You know a successful connection is set when a response containing a “PERMIT” or “DENY” in uppercase is returned as follows:
+    
+    .. code-block:: json
+       :caption: Response
+    
+        {
+          "decision": "PERMIT",
+          "details": "Decision Permit. OK!"
+        }
+
+**Method 2: curl**
+
+    This method does the same as the http command but uses the alternate command of curl. The command should have the following form:
+
+    .. code-block:: bash 
+    
+        curl -u <user>:<pass> -H "Content-Type: application/json" -H "ClientAuth:<yourClientAuth>" 
+             -H "Environment:<environment>" -X POST -d @guard_req.json pdp:8081/pdp/api/getDecision
+
+    * Note that <user> and <pass> are in plain text, while the other headers follow the same form as in Method 1 above.
+    * This request will need further configuration if you are using a proxy
+    * The response is the same as in Method 1.
+
+
+**Note on Proxies**
+
+    * JVM system properties should be set if a proxy is being used to make the connection work with policy.
+    * The connection may succeed but have response code 401 or 403 with improper proxy authentication, which leads to "Indeterminate"
+    * Additionally, the CLI tools have specific proxy configuration. See their respective manual pages for more info.
+
+
+End of Document
+
+.. SSNote: Wiki page ref.  https://wiki.onap.org/display/DW/Using+guard+in+the+PDP-D
diff --git a/docs/platform/index.rst b/docs/platform/index.rst
index 19866e24d..3d501fb55 100644
--- a/docs/platform/index.rst
+++ b/docs/platform/index.rst
@@ -1,7 +1,7 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 
-Policy Engine
--------------
+Policy Engine Platform
+----------------------
 
 .. toctree::
    :maxdepth: 1
@@ -12,3 +12,5 @@ Policy Engine
    policygui.rst
    guardpolicy.rst
    deployPDPPAP.rst
+   guardpdp.rst
+
diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst
index a10f02689..cd9388f7a 100644
--- a/docs/platform/installation.rst
+++ b/docs/platform/installation.rst
@@ -313,3 +313,6 @@ Installation Complete
 .. _Standalone Quick Start : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Standalone+Quick+Start
 
 
+
+End of Document
+
diff --git a/docs/platform/offeredapis.rst b/docs/platform/offeredapis.rst
index 8d4cfebd1..811a12891 100644
--- a/docs/platform/offeredapis.rst
+++ b/docs/platform/offeredapis.rst
@@ -45,5 +45,5 @@ Additional information, including examples, can be found at `PolicyApi link`_.
 
 
 
-End of document
+End of Document