blob: f53357bbd6977fb9cc680d7cd390f2d44432216d [file] [log] [blame]
Saryu Shah3198d6d2017-11-07 21:40:27 +00001
2.. This work is licensed under a Creative Commons Attribution 4.0 International License.
3.. http://creativecommons.org/licenses/by/4.0
4
5************************
6Using guard in the PDP-D
7************************
8
9.. contents::
10 :depth: 3
11
12This 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
14Configuration
15^^^^^^^^^^^^^
16
17Prerequisites
18-------------
19
20Stop 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
27Guard 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
46PDP-X Properties
47----------------
48
49For 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
67Verification
68^^^^^^^^^^^^
69
70It is recommended to test using CLI tools before running since changing bash command parameters are faster than restarting policy.
71
72Logs Verification
73-----------------
74Checking 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.
75You 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
77CLI Verification
78----------------
79
80It 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
151End of Document
152
153.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Using+guard+in+the+PDP-D