1 |
<?xml version="1.0"?> |
---|
2 |
<section> |
---|
3 |
<title>REST operation over HTTP</title> |
---|
4 |
|
---|
5 |
<para> |
---|
6 |
A variety of operational read and write operations are available over |
---|
7 |
HTTP. The HTTP layer is only available over SSL (HTTPS), operates on |
---|
8 |
the IANA assigned port number 43191. The SSL implementation of the |
---|
9 |
wire protocol requires client certificates, so this REST mechansim is |
---|
10 |
only available to HTTP clients that support both SSL and user-supplied |
---|
11 |
client certificates. The client certificates must be signed by a |
---|
12 |
certificate authority recognized by the <command>noitd</command> |
---|
13 |
instance. |
---|
14 |
</para> |
---|
15 |
|
---|
16 |
<section> |
---|
17 |
<title>Manipulating Checks</title> |
---|
18 |
|
---|
19 |
<section> |
---|
20 |
<title>/checks/show/</title> |
---|
21 |
<variablelist> |
---|
22 |
<varlistentry> |
---|
23 |
<term>method</term> |
---|
24 |
<listitem><code>GET</code></listitem> |
---|
25 |
</varlistentry> |
---|
26 |
<varlistentry> |
---|
27 |
<term>uri</term> |
---|
28 |
<listitem><code>/checks/show/<path/><checkid></code></listitem> |
---|
29 |
</varlistentry> |
---|
30 |
</variablelist> |
---|
31 |
<para> |
---|
32 |
This call returns an XML document describing the current configuration and |
---|
33 |
state of the specific check. The <code>checkid</code> specified is located |
---|
34 |
under the optional <code>path</code>. If the check exists, but it under |
---|
35 |
another path, a HTTP 403 code is returned. If the check does not exist, |
---|
36 |
a HTTP 404 code is returned. |
---|
37 |
</para> |
---|
38 |
|
---|
39 |
<example> |
---|
40 |
<title>REST /checks/show XML output.</title> |
---|
41 |
<para>Output from an HTTP GET of <code>/checks/show/1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</code></para> |
---|
42 |
<programlisting><![CDATA[ |
---|
43 |
<?xml version="1.0" encoding="utf8"?> |
---|
44 |
<check> |
---|
45 |
<attributes> |
---|
46 |
<uuid>1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</uuid> |
---|
47 |
<name>http</name> |
---|
48 |
<module inherited="/dc1/web/@module">http</module> |
---|
49 |
<target>8.8.38.5</target> |
---|
50 |
<period inherited="/dc1/@period">60000</period> |
---|
51 |
<timeout inherited="/dc1/@timeout">5000</timeout> |
---|
52 |
<filterset inherited="/@filterset">default</filterset> |
---|
53 |
</attributes> |
---|
54 |
<config> |
---|
55 |
<code>200</code> |
---|
56 |
<url>https://labs.omniti.com/</url> |
---|
57 |
</config> |
---|
58 |
<state> |
---|
59 |
<running>false</running> |
---|
60 |
<killed>false</killed> |
---|
61 |
<configured>true</configured> |
---|
62 |
<disabled>false</disabled> |
---|
63 |
<last_run now="1253124365.131">1253124339.270</last_run> |
---|
64 |
<runtime>4.408</runtime> |
---|
65 |
<availability>available</availability> |
---|
66 |
<state>good</state> |
---|
67 |
<status>code=200,rt=4.409s,bytes=8958</status> |
---|
68 |
<metrics> |
---|
69 |
<duration type="I">4408</duration> |
---|
70 |
<code type="s">200</code> |
---|
71 |
<bytes type="i">8958</bytes> |
---|
72 |
</metrics> |
---|
73 |
</state> |
---|
74 |
</check> |
---|
75 |
]]></programlisting> |
---|
76 |
</example> |
---|
77 |
</section> |
---|
78 |
|
---|
79 |
<section> |
---|
80 |
<title>/checks/set/</title> |
---|
81 |
<variablelist> |
---|
82 |
<varlistentry> |
---|
83 |
<term>method</term> |
---|
84 |
<listitem><code>PUT</code></listitem> |
---|
85 |
</varlistentry> |
---|
86 |
<varlistentry> |
---|
87 |
<term>uri</term> |
---|
88 |
<listitem><code>/checks/set/<path/><checkid></code></listitem> |
---|
89 |
</varlistentry> |
---|
90 |
</variablelist> |
---|
91 |
<para> |
---|
92 |
This call accepts a document describing a check. That check is |
---|
93 |
instantiated with the <code>checkid</code> specified in the URL. If the |
---|
94 |
check exists, but is not under the provided optional <code>path</code> a |
---|
95 |
HTTP 403 code is returned. If the check already exists under the specified |
---|
96 |
<code>path</code>, the check is updated to reflect the new configuration. |
---|
97 |
The <code>module</code> cannot be changed for existing checks. All other |
---|
98 |
fields can be changed. All fields are required except the |
---|
99 |
<code>disable</code> field; if disable is omitted, it will inherit the |
---|
100 |
disable attribute from parents in the tree (use the default setting). |
---|
101 |
On success, a HTTP 200 is returned and an XML documented that matches the |
---|
102 |
format of the <code>/check/show</code> REST command. |
---|
103 |
The input is as follows: |
---|
104 |
</para> |
---|
105 |
|
---|
106 |
<example> |
---|
107 |
<title>REST /checks/set XML input.</title> |
---|
108 |
<programlisting><![CDATA[ |
---|
109 |
<?xml version="1.0" encoding="utf8"?> |
---|
110 |
<check> |
---|
111 |
<attributes> |
---|
112 |
<name>http</name> |
---|
113 |
<module>http</module> |
---|
114 |
<target>8.8.38.5</target> |
---|
115 |
<period>60000</period> |
---|
116 |
<timeout>5000</timeout> |
---|
117 |
<filterset>default</filterset> |
---|
118 |
</attributes> |
---|
119 |
<config> |
---|
120 |
<code>200</code> |
---|
121 |
<url>https://labs.omniti.com/</url> |
---|
122 |
</config> |
---|
123 |
</check> |
---|
124 |
]]></programlisting> |
---|
125 |
</example> |
---|
126 |
</section> |
---|
127 |
<section> |
---|
128 |
<title>/checks/delete/</title> |
---|
129 |
<variablelist> |
---|
130 |
<varlistentry> |
---|
131 |
<term>method</term> |
---|
132 |
<listitem><code>DELETE</code></listitem> |
---|
133 |
</varlistentry> |
---|
134 |
<varlistentry> |
---|
135 |
<term>uri</term> |
---|
136 |
<listitem><code>/checks/delete/<path/><checkid></code></listitem> |
---|
137 |
</varlistentry> |
---|
138 |
</variablelist> |
---|
139 |
<para> |
---|
140 |
This call returns deletes the specified check. If the check does not |
---|
141 |
exist, then a HTTP 404 code is returned. If the check exists, but is |
---|
142 |
outside of the optional <code>path</code>, then a HTTP 403 code is |
---|
143 |
returned. Otherwise, the specified check is removed from the system |
---|
144 |
and a HTTP 200 is returned. Any response payload returned should be |
---|
145 |
ignored by the client. |
---|
146 |
</para> |
---|
147 |
</section> |
---|
148 |
|
---|
149 |
</section> |
---|
150 |
|
---|
151 |
<section> |
---|
152 |
<title>Manipulating Filters</title> |
---|
153 |
|
---|
154 |
<section> |
---|
155 |
<title>/filters/show/</title> |
---|
156 |
<variablelist> |
---|
157 |
<varlistentry> |
---|
158 |
<term>method</term> |
---|
159 |
<listitem><code>GET</code></listitem> |
---|
160 |
</varlistentry> |
---|
161 |
<varlistentry> |
---|
162 |
<term>uri</term> |
---|
163 |
<listitem><code>/filters/show/<path/><filterset></code></listitem> |
---|
164 |
</varlistentry> |
---|
165 |
</variablelist> |
---|
166 |
<para> |
---|
167 |
This call returns an XML document describing the current configuration |
---|
168 |
of the specified filterset. The <code>filterset</code> specified is located |
---|
169 |
under the optional <code>path</code>. If the check exists, but it under |
---|
170 |
another path, a HTTP 403 code is returned. If the check does not exist, |
---|
171 |
a HTTP 404 code is returned. |
---|
172 |
</para> |
---|
173 |
|
---|
174 |
<example> |
---|
175 |
<title>REST /filters/show XML output.</title> |
---|
176 |
<para>Output from an HTTP GET of <code>/filters/show/default</code></para> |
---|
177 |
<programlisting><![CDATA[ |
---|
178 |
<?xml version="1.0" encoding="utf8"?> |
---|
179 |
<filterset> |
---|
180 |
<rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/> |
---|
181 |
</filterset> |
---|
182 |
]]></programlisting> |
---|
183 |
</example> |
---|
184 |
</section> |
---|
185 |
|
---|
186 |
<section> |
---|
187 |
<title>/filters/set/</title> |
---|
188 |
<variablelist> |
---|
189 |
<varlistentry> |
---|
190 |
<term>method</term> |
---|
191 |
<listitem><code>PUT</code></listitem> |
---|
192 |
</varlistentry> |
---|
193 |
<varlistentry> |
---|
194 |
<term>uri</term> |
---|
195 |
<listitem><code>/filters/set/<path/><filterset></code></listitem> |
---|
196 |
</varlistentry> |
---|
197 |
</variablelist> |
---|
198 |
<para> |
---|
199 |
This call accepts a document describing a filterset. That filterset is |
---|
200 |
instantiated with the name <code>filterset</code> specified in the URL. |
---|
201 |
If the filterset exists, but is not under the provided optional |
---|
202 |
<code>path</code> a HTTP 403 code is returned. If the filterset already |
---|
203 |
exists under the specified <code>path</code>, the filterset is replaced |
---|
204 |
with the configuration submitted. |
---|
205 |
On success, a HTTP 200 is returned and an XML documented that matches the |
---|
206 |
format of the <code>/check/show</code> REST command. |
---|
207 |
The input is as follows: |
---|
208 |
</para> |
---|
209 |
|
---|
210 |
<example> |
---|
211 |
<title>REST /filtert/set XML input.</title> |
---|
212 |
<programlisting><![CDATA[ |
---|
213 |
<?xml version="1.0" encoding="utf8"?> |
---|
214 |
<filterset> |
---|
215 |
<rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/> |
---|
216 |
</filterset> |
---|
217 |
]]></programlisting> |
---|
218 |
</example> |
---|
219 |
</section> |
---|
220 |
<section> |
---|
221 |
<title>/filters/delete/</title> |
---|
222 |
<variablelist> |
---|
223 |
<varlistentry> |
---|
224 |
<term>method</term> |
---|
225 |
<listitem><code>DELETE</code></listitem> |
---|
226 |
</varlistentry> |
---|
227 |
<varlistentry> |
---|
228 |
<term>uri</term> |
---|
229 |
<listitem><code>/filters/delete/<path/><filterset></code></listitem> |
---|
230 |
</varlistentry> |
---|
231 |
</variablelist> |
---|
232 |
<para> |
---|
233 |
This call returns deletes the specified filterset. If the filterset does |
---|
234 |
not exist, then a HTTP 404 code is returned. If the filterset exists, but |
---|
235 |
is outside of the optional <code>path</code>, then a HTTP 403 code is |
---|
236 |
returned. Otherwise, the specified filterset is removed from the system |
---|
237 |
and a HTTP 200 is returned. Any response payload returned should be |
---|
238 |
ignored by the client. |
---|
239 |
</para> |
---|
240 |
</section> |
---|
241 |
|
---|
242 |
</section> |
---|
243 |
</section> |
---|