docs/platform/guardpdp.rst

   1
   2 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 ************************
   6 Using guard in the PDP-D
   7 ************************
   8
   9 .. contents::
  10     :depth: 3
  11
  12 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.
  13
  14 Configuration
  15 ^^^^^^^^^^^^^
  16
  17 Prerequisites
  18 -------------
  19
  20 Stop Policy, open, and verify the config:
  21
  22 - Stop policy with *policy stop*
  23 - Open *$POLICY_HOME/config/controlloop.properties.environment*
  24 - Make sure the *sql.db.host*, *sql.db.username* and *sql.db.password* are set correctly
  25
  26
  27 Guard Properties
  28 ----------------
  29
  30 **guard.url** - URL endpoint of the PDP-X which will receive the request.
  31     - For example, *http://pdp:8081/pdp/api/getDecision* will connect to the localhost PDP-X.
  32     - This request requires some configuration for PDP-X properties below.
  33     - For testing this URL before running policy, see Verification below.
  34
  35 **guard.jdbc.url** - URL of the database location to which the operations history will be written.
  36     - For example, *jdbc:mariadb://mariadb:3306/onap_sdk*.
  37     - Note that the port is included.
  38     - Note that at the end, the database name is used.
  39
  40 **guard.disabled** - For enabling / disabling guard functionality.
  41     - For example, to enable set it to false.
  42     - When this is set to true, the previous two properties will be ignored.
  43     - If guard is enabled, then the following PDP-X properties must also be set.
  44
  45
  46 PDP-X Properties
  47 ----------------
  48
  49 For testing these properties before running policy, see Verification below.
  50
  51 **pdpx.host** - URL of the PDP-X
  52     - For example, pdp can be used when PDP-X is on localhost.
  53
  54 **pdpx.username** - User to authenticate
  55
  56 **pdpx.password** - User Password
  57
  58 **pdpx.environment** - Environment making requests
  59     - For example, TEST
  60
  61 **pdpx.client.username** - Client to authenticate
  62
  63 **pdpx.client.password** - Client password
  64
  65
  66
  67 Verification
  68 ^^^^^^^^^^^^
  69
  70 It is recommended to test using CLI tools before running since changing bash command parameters are faster than restarting policy.
  71
  72 Logs Verification
  73 -----------------
  74 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.
  75 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.
  76
  77 CLI Verification
  78 ----------------
  79
  80 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.
  81
  82 **Method 1: httpie - CLI, cURL-like tool for humans**
  83
  84     Using the http command we can make a request directly to PDP-X from the command line. Use the following form:
  85
  86     .. code-block:: bash
  87
  88         http
  89          POST pdp:8081/pdp/api/getDecision
  90          Authorization:<yourAuth> ClientAuth:<yourClientAuth>
  91          Environment:<environment> Content-Type:application/json < guard_request.json
  92
  93     | where:
  94     |     *<yourAuth>*       is the string generated from user:pass converted to base64 encoding
  95     |                        (a conversion tool is available at https://www.base64encode.org/)
  96     |     *<yourClientAuth>* is generated the same way but from the client user and pass.
  97     |     *<environment>*    is the context of the request. For example: TEST
  98     |     *pdp*              is the host of the PDP-X
  99
 100
 101     The guard_request.json should be in the form of the following:
 102
 103     .. code-block:: json
 104        :caption: guard_request.json
 105
 106         {
 107           "decisionAttributes": {
 108                 "actor": "APPC",
 109                 "recipe": "Restart",
 110                 "target": "test13",
 111                 "clname" : "piptest"
 112             },
 113           "onapName": "PDPD"
 114         }
 115
 116     * This request uses Basic Access Authentication.
 117     * This request will need further configuration if you are using a proxy.
 118
 119
 120     You know a successful connection is set when a response containing a “PERMIT” or “DENY” in uppercase is returned as follows:
 121
 122     .. code-block:: json
 123        :caption: Response
 124
 125         {
 126           "decision": "PERMIT",
 127           "details": "Decision Permit. OK!"
 128         }
 129
 130 **Method 2: curl**
 131
 132     This method does the same as the http command but uses the alternate command of curl. The command should have the following form:
 133
 134     .. code-block:: bash
 135
 136         curl -u <user>:<pass> -H "Content-Type: application/json" -H "ClientAuth:<yourClientAuth>"
 137              -H "Environment:<environment>" -X POST -d @guard_req.json pdp:8081/pdp/api/getDecision
 138
 139     * Note that <user> and <pass> are in plain text, while the other headers follow the same form as in Method 1 above.
 140     * This request will need further configuration if you are using a proxy
 141     * The response is the same as in Method 1.
 142
 143
 144 **Note on Proxies**
 145
 146     * JVM system properties should be set if a proxy is being used to make the connection work with policy.
 147     * The connection may succeed but have response code 401 or 403 with improper proxy authentication, which leads to "Indeterminate"
 148     * Additionally, the CLI tools have specific proxy configuration. See their respective manual pages for more info.
 149
 150
 151 End of Document
 152
 153 .. SSNote: Wiki page ref.  https://wiki.onap.org/display/DW/Using+guard+in+the+PDP-D