Saryu Shah | 3198d6d | 2017-11-07 21:40:27 +0000 | [diff] [blame^] | 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, *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 |