1 |
root |
1.1 |
=head1 DESCRIPTION |
2 |
|
|
|
3 |
|
|
This document describes the porttracker API for third-party programs to |
4 |
|
|
use (it is also used internally to communicate with the tawnyd). |
5 |
|
|
|
6 |
|
|
=head1 CONVENTIONS |
7 |
|
|
|
8 |
|
|
In this document, command names, paths and similar entities are F<formatted like this>. |
9 |
|
|
|
10 |
|
|
Preformatted sections are indented like this. This is used for verbatim |
11 |
|
|
text. Portions of the section that need to be replaced by dynamic |
12 |
|
|
content are enclosed in <angle brackets>. |
13 |
|
|
|
14 |
|
|
< Lines starting with "< " are received from the server. |
15 |
|
|
> Lines starting with "> " are sent to the server. # and this is a comment |
16 |
|
|
|
17 |
|
|
Both text refering to these variable sections and verbatim text inside |
18 |
|
|
other paragraphs is formatted C<like this>. |
19 |
|
|
|
20 |
|
|
=head1 OVERVIEW |
21 |
|
|
|
22 |
|
|
=head2 SOCKET LAYER |
23 |
|
|
|
24 |
|
|
The API uses a tcp connection to port 55 on the porttracker management |
25 |
|
|
machine. The TCP connection must be 8-bit-clean (as UTF-8 is used as |
26 |
|
|
character encoding) and can be driven either in binary or text mode. |
27 |
|
|
|
28 |
|
|
Alternatively, the server also listens on the Unix socket |
29 |
|
|
F</tmp/.tawny/.tawnyd> for local connections (where "none" is one of the |
30 |
|
|
guaranteed auth methods). |
31 |
|
|
|
32 |
|
|
=head2 PACKAGE ENCAPSULATION LAYER |
33 |
|
|
|
34 |
|
|
The protocol is based on sending and receiving JSON arrays encoded as |
35 |
|
|
UTF-8. The server expects JSON arrays to be sent back-to-back, without any |
36 |
|
|
separators, but for testing purposes it is often convenient to end JSON |
37 |
|
|
arrays with ASCII LF (or ASCII CR LF) characters ("newline"), effectively |
38 |
|
|
treating it as a line-based protocol. |
39 |
|
|
|
40 |
|
|
To support programming languages without incremental JSON parsers, |
41 |
|
|
the server will append an ASCII LF character to each JSON array and |
42 |
|
|
additionally will make sure that its replies will never contain any ASCII |
43 |
|
|
LF characters, so instead of directly parsing the JSON stream, the client |
44 |
|
|
may also read single lines and then decode the JSON array contained in |
45 |
|
|
each line. |
46 |
|
|
|
47 |
|
|
Note 1: This means that one can use C<telnet> or a similar program to test |
48 |
|
|
the protocol, as the server ignores ASCII CR and LF characters but sends |
49 |
|
|
its responses as single lines. |
50 |
|
|
|
51 |
|
|
Note 2: There are two principal parsing strategies: the obvious one is to |
52 |
|
|
read a single (potentially very large) line and then decode it, and the |
53 |
|
|
less obvious one is to use a streaming parser and simply read JSON arrays |
54 |
|
|
one after each other. |
55 |
|
|
|
56 |
|
|
=head2 MESSAGE LAYER |
57 |
|
|
|
58 |
|
|
Server and client can send messages to each other at any time (usually the |
59 |
|
|
client first has to wait and parse the initial server greeting, though, to |
60 |
|
|
see what kind of authentication is required). |
61 |
|
|
|
62 |
|
|
All messages are JSON arrays in one of the following formats: |
63 |
|
|
|
64 |
|
|
[<id>, <type>, <args...>] # client request |
65 |
|
|
[<id>, <status>, <args...>] # server response |
66 |
|
|
[null, <type>, <args...>] # server notification |
67 |
|
|
|
68 |
|
|
The first member, C<id>, identifies the request/response pair: Each |
69 |
|
|
request the client sends has to use a unique ID not currently in use |
70 |
|
|
by any request that is still ongoing. Any string or number can be |
71 |
|
|
used for the C<id> value. The C<type> member is a string indicating |
72 |
|
|
the type of request to the server. The remaining members (if any) are |
73 |
|
|
request-specific. |
74 |
|
|
|
75 |
|
|
Each server response to a request will use the same C<id> value as the |
76 |
|
|
request. The second member, C<status>, is either C<0> for failure, |
77 |
|
|
followed by an error message and optionally more information, or C<1> for |
78 |
|
|
success and request-specific return values. |
79 |
|
|
|
80 |
|
|
The protocol supports pipelining (sending multiple requests without |
81 |
|
|
processing any replies) and responses to a request can come in any |
82 |
|
|
order. Most requests will be handled in parallel, only some (like the |
83 |
|
|
login messages) are guaranteed to get processed in order. |
84 |
|
|
|
85 |
|
|
If the first member is the JSON C<null> value, then the message is a |
86 |
|
|
server notification and the C<type> member identified the notification |
87 |
|
|
type. This mechanism is used for the initial server greeting and any fatal |
88 |
|
|
errors (such as wrongly formatted client requests). |
89 |
|
|
|
90 |
|
|
Note: The type model used for JSON is "soft", that is, numbers might |
91 |
|
|
sometimes be returned as strings, and vice versa. The only values in the |
92 |
|
|
protocol where you can be sure of the type are the C<id> and status return |
93 |
|
|
values, for other values you have to be liberal in what you accept. |
94 |
|
|
|
95 |
|
|
|
96 |
|
|
=head1 SESSION STRUCTURE |
97 |
|
|
|
98 |
|
|
When connecting, the server sends a server greeting notification |
99 |
|
|
("hello"), informing the client of the protocol version, whether |
100 |
|
|
authentication is required and which kind of authentication is supported. |
101 |
|
|
|
102 |
|
|
If the server indicated that authentication is required, the client will |
103 |
|
|
then have to send login requests until it successfully authenticated. |
104 |
|
|
|
105 |
|
|
After that, the server will continue serving client requests. |
106 |
|
|
|
107 |
|
|
To end a session, the client just should simply drop the connection. |
108 |
|
|
|
109 |
|
|
|
110 |
|
|
=head1 EXAMPLE SESSION |
111 |
|
|
|
112 |
|
|
< [null,"hello",1,["login"]] |
113 |
|
|
Server sent the initial greeting and requests the |
114 |
|
|
use of a login request for authentication. |
115 |
|
|
|
116 |
|
|
> ["someid", "realm_poll", 5100005442] |
117 |
|
|
< ["someid",0,"you need to authenticate first"] |
118 |
|
|
Most requests are only valid once logged-in. |
119 |
|
|
|
120 |
|
|
> [100, "login", "username", "password"] |
121 |
|
|
< [100,1] |
122 |
|
|
The client sent a login request with credentials, |
123 |
|
|
and the server accepted them. |
124 |
|
|
|
125 |
|
|
> ["someid", "realm_poll", 5100005442] |
126 |
|
|
Starts a poll, which takes a long time. |
127 |
|
|
|
128 |
|
|
> [3, "ping"] |
129 |
|
|
< [3,1,1202674637.64799,17372] |
130 |
|
|
Ping simply returns a timestamp and the daemon pid as fast as possible. |
131 |
|
|
|
132 |
|
|
> ["someid",1,{"port_updates":"2","device_seens":"88","device_inserts":"9","switch_updates":"3","port_seens":"73"}] |
133 |
|
|
The result of the poll, with some statistical data. |
134 |
|
|
|
135 |
|
|
|
136 |
|
|
=head1 MESSAGE TYPES |
137 |
|
|
|
138 |
|
|
Messages might contain more than the documented number of array |
139 |
|
|
members. If that is the case, the application must simply ignore them. |
140 |
|
|
|
141 |
|
|
=head2 NOTIFICATIONS |
142 |
|
|
|
143 |
|
|
=over 4 |
144 |
|
|
|
145 |
|
|
=item "hello" - initial server greeting |
146 |
|
|
|
147 |
|
|
< [null, "hello", <version>, [<auth-types...>], <nonce>] |
148 |
|
|
|
149 |
|
|
The server usually sends this notification after the initial connect and |
150 |
|
|
never thereafter. The C<version> argument specified the protocol version |
151 |
|
|
(always C<1>), the C<auth-types> argument is an array of authentication |
152 |
|
|
types that the server accepts (there can be more than one). The nonce can |
153 |
|
|
be used to securely authenticate, and is base64-encoded. |
154 |
|
|
|
155 |
|
|
Before a client is authenticated, all other requests will fail. |
156 |
|
|
|
157 |
|
|
The defined authentication types are: |
158 |
|
|
|
159 |
|
|
=over 4 |
160 |
|
|
|
161 |
|
|
=item "none" |
162 |
|
|
|
163 |
|
|
No additional authentication is required, the client can simply |
164 |
|
|
start sending other requests. This is available when the server |
165 |
|
|
detects a "secure" connection, e.g. from the local host, or when other |
166 |
|
|
authentication methods are used, such as an SSL certificate or IP-based |
167 |
|
|
authentication. |
168 |
|
|
|
169 |
|
|
=item "login" |
170 |
|
|
|
171 |
|
|
The client may use password authentication by sending a login request |
172 |
|
|
(described later). |
173 |
|
|
|
174 |
|
|
=item "login_cram_md6" |
175 |
|
|
|
176 |
|
|
The client may use a challenge response mechanism based on MD6 to authenticate. |
177 |
|
|
|
178 |
|
|
=back |
179 |
|
|
|
180 |
|
|
=item "info" - an informational message |
181 |
|
|
|
182 |
|
|
< [null, "info", <informational-message>] |
183 |
|
|
|
184 |
|
|
The server sends an informational message. These can be ignored by the |
185 |
|
|
client, or logged, depending on taste. |
186 |
|
|
|
187 |
|
|
=item "error" - a fatal error has occured |
188 |
|
|
|
189 |
|
|
< [null, "error", <error-message>] |
190 |
|
|
|
191 |
|
|
A fatal error has occurred. This should be logged, and the connection |
192 |
|
|
should probably be closed if the cause cannot be identified, as this |
193 |
|
|
signifies fatal events such as a non-decodable request or runtime errors |
194 |
|
|
in the server. |
195 |
|
|
|
196 |
|
|
=item "start_tls" - TLS negotiation starts |
197 |
|
|
|
198 |
|
|
< [null, "start_tls"] |
199 |
|
|
|
200 |
|
|
This notice is sent when the server wants to start TLS/SSL negotiation, |
201 |
|
|
either because the server requires TLS to proceed, or because the client |
202 |
|
|
requested it via a C<start_tls> request. |
203 |
|
|
|
204 |
|
|
TLS negotiation will start directly after the final ASCII LF ending the |
205 |
|
|
notice. The protocol will continue as normal after the TLS handshake. |
206 |
|
|
|
207 |
|
|
=back |
208 |
|
|
|
209 |
|
|
|
210 |
|
|
=head2 REQUESTS AND RESPONSES |
211 |
|
|
|
212 |
|
|
=over 4 |
213 |
|
|
|
214 |
|
|
=item "login" - username/password-based authentication |
215 |
|
|
|
216 |
|
|
> [<id>, "login", <username>, <password>] |
217 |
|
|
< [<id>, 1] |
218 |
|
|
|
219 |
|
|
Tries to log-in with the given username and password. The username |
220 |
|
|
and password must belong to a valid admin user configured in the user |
221 |
|
|
interface. |
222 |
|
|
|
223 |
|
|
=item "login_cram_md6" - secure username/password-based authentication |
224 |
|
|
|
225 |
|
|
> [<id>, "login_cram_md6", <username>, <cr>, <cc>] |
226 |
|
|
< [<id>, 1, <sr>] |
227 |
|
|
|
228 |
|
|
Tries to securely login with a username and password. First, a shared key |
229 |
|
|
is calculated, by using (all MD6 invocations are with blocksize 64 and |
230 |
|
|
hashsize 256): |
231 |
|
|
|
232 |
|
|
key = hmac_md6 (password, username) # as defined by RFC 2104 |
233 |
|
|
|
234 |
|
|
Then, the client generates a a nonce of any length (empty nonces are ok), |
235 |
|
|
called C<cc>. Then it calculates C<cr> using the C<key>, C<cc> and the |
236 |
|
|
server C<nonce> as follows ("+" means concatenation): |
237 |
|
|
|
238 |
|
|
cr = hmac_md6 (key, cc + nonce) |
239 |
|
|
|
240 |
|
|
Then it sends both C<cr> and C<cc> in the login request, base64-encoded. |
241 |
|
|
|
242 |
|
|
If authentication is successful, the server responds with a base64-encoded |
243 |
|
|
C<sr>: |
244 |
|
|
|
245 |
|
|
sr = hmac_md6 (key, nonce + cc) |
246 |
|
|
|
247 |
|
|
If the client used a non-empty C<cc>, then it can use the C<sr> value to |
248 |
|
|
shield against man-in-the-middle attacks by comparing it with its own |
249 |
|
|
calculation. |
250 |
|
|
|
251 |
|
|
Test vectors: |
252 |
|
|
|
253 |
|
|
nonce/base64 = YWVlYWJkZjQzMWEzYWM2 |
254 |
|
|
username/text = user |
255 |
|
|
password/text = pass |
256 |
|
|
key/base64 = C1JQ4jnjsrBzJtTZXt8Po+wA/iXtaM5r4BIIjl0lfMA |
257 |
|
|
cc/base64 = ZmZiOTczMjE= |
258 |
|
|
cr/base64 = 5UJKUqehqBKwXiSk6RzYjsPWqivMJcEgE2crTLVyw04 |
259 |
|
|
sr/base64 = gGKEpOuv5WuuQ7ZbwDWNIdyJtAnCimVN/faM5qWtOZM |
260 |
|
|
|
261 |
|
|
=item "ping" - ping the server, return some informational data |
262 |
|
|
|
263 |
|
|
> [<id>, "ping"] |
264 |
|
|
< [<id>, 1, <timestamp>, <server-pid>] |
265 |
|
|
|
266 |
|
|
=item "start_tls" - request SSL/TLS handshake |
267 |
|
|
|
268 |
|
|
> [<id>, "start_tls"] |
269 |
|
|
< [null, "start_tls"] |
270 |
|
|
<--tls negotiation--> |
271 |
|
|
< [<id>, 1] |
272 |
|
|
|
273 |
|
|
This request request TLS negotiation. If accepted, the server replies |
274 |
|
|
first with a C<start_tls> notification, followed by the TLS handshake, |
275 |
|
|
followed by the request reply. If TLS is rejected, then there will be no |
276 |
|
|
notification and no handshake, just the reply. |
277 |
|
|
|
278 |
|
|
|
279 |
|
|
The client must not send anything after sending this request until |
280 |
|
|
the server sends a C<start_tls> notification (i.e. nothing must be |
281 |
|
|
written after the closing C<]> until either a reply or a notification is |
282 |
|
|
received). |
283 |
|
|
|
284 |
|
|
The handshake must be started immediately after the final ASCII LF that |
285 |
|
|
ends the notification reply. |
286 |
|
|
|
287 |
|
|
Note that it is quite possible to receive other responses and |
288 |
|
|
notifications before the TLS notification is received. |
289 |
|
|
|
290 |
|
|
=item "product_id" - return the product id |
291 |
|
|
|
292 |
|
|
> [<id>, "product_id"] |
293 |
|
|
< [<id>, 1, "n", <product-id>] |
294 |
|
|
|
295 |
|
|
Example: |
296 |
|
|
|
297 |
|
|
> [1,"product_id"] |
298 |
|
|
< [1,1,"n","00:1d:60:e8:6e:36"] |
299 |
|
|
|
300 |
|
|
Returns the license type ("n") and product ID for licencing purposes. |
301 |
|
|
|
302 |
|
|
=item "set_license" - configure a new licence |
303 |
|
|
|
304 |
|
|
> [<id>, "set_license", <license-string<] |
305 |
|
|
< [<id>, <status>] |
306 |
|
|
|
307 |
|
|
Configures the given licence string as new licence for the box. Returns |
308 |
|
|
successful if the licence is valid, fails otherwise. |
309 |
|
|
|
310 |
|
|
Setting the license requires admin privileges. |
311 |
|
|
|
312 |
|
|
=item "realm_info" - information about realms |
313 |
|
|
|
314 |
|
|
> [<id>, "realm_info", [<fields...>], [<realms...>]] |
315 |
|
|
< [<id>, 1, [ [<fields...>]... ]] |
316 |
|
|
|
317 |
|
|
Example: |
318 |
|
|
|
319 |
|
|
> [1,"realm_info",["gid","description","polling","name","seeds"]] |
320 |
|
|
< [1,1,["5000015442","","0","Realm Name","192.168.33.19"]] |
321 |
|
|
|
322 |
|
|
> [1, "realm_info", ["gid", "discovery_result", "poll_result", "sync_result"]] |
323 |
|
|
< [1,1,["64424509927",{"infrastructure":13},{"poll":{"infrastructure":13, |
324 |
|
|
"ports":"339","end":"79"}},{"sync":{"qsync":null,"bsync":"Success"}}]] |
325 |
|
|
|
326 |
|
|
Requests information about the given realms (or all realms if specified as |
327 |
|
|
C<null>). The following fields can be requested, and their contents will be |
328 |
|
|
returned in the order specified in the C<fields> array: |
329 |
|
|
|
330 |
|
|
=over 4 |
331 |
|
|
|
332 |
|
|
=item gid - the gid (id value) identifying the realm |
333 |
|
|
|
334 |
|
|
=item name - the user-specified name of the realm |
335 |
|
|
|
336 |
|
|
=item description - the user-specified description for this realm |
337 |
|
|
|
338 |
|
|
=item last_discover - timestamp of last discover run |
339 |
|
|
|
340 |
|
|
=item last_poll - timestamp of last poll run |
341 |
|
|
|
342 |
|
|
=item last_sync - timestamp of last sync run |
343 |
|
|
|
344 |
|
|
=item polling - 0 (not polling) or 1 (currently polling) |
345 |
|
|
|
346 |
|
|
=item syncing - 0 (not syncing) or 1 (currently syncing) |
347 |
|
|
|
348 |
|
|
=item seeds - the seed list (whitespace-separated list of seed devices) |
349 |
|
|
|
350 |
|
|
=item pollers - a list of poller-gids of pollers attached to the realm |
351 |
|
|
|
352 |
|
|
=item discovery_result - a hash with key as infrastructure and value as number of devices discovered |
353 |
|
|
|
354 |
|
|
=item poll_result - a hash with keys infrastructure, ports and end and values as their counts |
355 |
|
|
|
356 |
|
|
=item sync_result - a hash with keys qsync and bsync and values as their results |
357 |
|
|
|
358 |
|
|
=item ageing_interval - ping sweep interval for this realm. |
359 |
|
|
|
360 |
|
|
=back |
361 |
|
|
|
362 |
|
|
=item "realm_info_modify" - edits the given realm |
363 |
|
|
|
364 |
|
|
> [<id>, "realm_info_modify", <realm-gid>, {<prop>:<value>,...}] |
365 |
|
|
< [<id>, 1] |
366 |
|
|
|
367 |
|
|
A property hash followed by a realm gid. Keys of the hash are name, |
368 |
|
|
description, discovery_poller and ageing_interval. |
369 |
|
|
|
370 |
|
|
Example: |
371 |
|
|
|
372 |
|
|
> [1, "realm_info_modify", "38952865423", {"name":"default-1"}] |
373 |
|
|
< [1, 1] |
374 |
|
|
|
375 |
|
|
=item "realm_modify" - adds and/or deletes realms |
376 |
|
|
|
377 |
|
|
> [<id>, "realm_modify", [delete-ids...], [[add-realm],...]] |
378 |
|
|
< [<id>, 1] |
379 |
|
|
|
380 |
|
|
Two arrays expected as input. First array is a list of realm gids needs to be deleted. |
381 |
|
|
Second array is a list of realm needs to be added. An array per realm can contain |
382 |
|
|
realm name and description. |
383 |
|
|
|
384 |
|
|
Example: |
385 |
|
|
|
386 |
|
|
> [1, "realm_modify", ["38456782341"], [["Test Realm", "for test"]]] |
387 |
|
|
< [1, 1] |
388 |
|
|
|
389 |
|
|
=item "realm_discover" - run discovery on a given realm |
390 |
|
|
|
391 |
|
|
> [<id>, "realm_discover", <realm-gid>] |
392 |
|
|
< [<id>, 1] |
393 |
|
|
|
394 |
|
|
=item "realm_poll" - run a poll on a given realm |
395 |
|
|
|
396 |
|
|
> [<id>, "realm_poll", <realm-gid>] |
397 |
|
|
< [<id>, 1, { <statistical data> } ] |
398 |
|
|
|
399 |
|
|
=item "switch_poll" - run a poll on a given realm and switch ip |
400 |
|
|
|
401 |
|
|
> [<id>, "switch_poll", <realm-gid>, <switch ip>] |
402 |
|
|
< [<id>, 1, { <statistical data> } ] |
403 |
|
|
|
404 |
|
|
=item "realm_sync" - run a sync on a given realm and plugin |
405 |
|
|
|
406 |
|
|
> [<id>, "realm_sync", <realm-gid>, <sync module>] |
407 |
|
|
< [<id>, 1] |
408 |
|
|
|
409 |
|
|
The C<sync module> can be either bsync or qsync. |
410 |
|
|
|
411 |
|
|
=item "realm_query" - query the database |
412 |
|
|
|
413 |
|
|
This request executes a database query with filtering, much like the |
414 |
|
|
device and switch views work in the user interface. |
415 |
|
|
|
416 |
|
|
> [<id>, "realm_query", <realm-gid>, <type> |
417 |
|
|
[<column-name>...], [<raw-column-name]>...], |
418 |
|
|
{<column-name> : <filter-expression>...}, |
419 |
|
|
<history mask>, |
420 |
|
|
{<port unused period> : <unused value>} |
421 |
|
|
] |
422 |
|
|
< [<id>, 1, [ [<result-data>]... ]] |
423 |
|
|
|
424 |
|
|
The C<realm-gid> is the GID of the realm to query, as returned by |
425 |
|
|
C<real_info>. The C<type> is the string C<device>, C<switch> or |
426 |
|
|
C<switch_detail>, which corresponds to the device view, switch view or |
427 |
|
|
switch detail view. |
428 |
|
|
|
429 |
|
|
The first array of C<column-name>s specifies which columns should be |
430 |
|
|
returned. The second array of C<raw-column-name>s works likewise, but |
431 |
|
|
the values returned will be the "raw" (possibly octet-encoded) database |
432 |
|
|
contents. Specifying the same column name in both array causes undefined |
433 |
|
|
behaviour. |
434 |
|
|
|
435 |
|
|
The hash of C<column-name> => C<filter-expression> pairs specifies |
436 |
|
|
additional filters. The syntax for the C<filter-expression> is the same as |
437 |
|
|
the ones used by the GUI. |
438 |
|
|
|
439 |
|
|
The C<history mask> is the history selection option. |
440 |
|
|
Value 0 means C<current>, value 1 means C<All> and value 2 means |
441 |
|
|
C<All+Changes>. Default value is 0. |
442 |
|
|
|
443 |
|
|
The hash of C<port unused period> => C<unused> pairs specifies |
444 |
|
|
port unused time. The C<port unused period> can be days, months or years. |
445 |
|
|
|
446 |
|
|
The reply contains an array of result rows. Each row consists of data |
447 |
|
|
values using the same ordering as in the requested column-name arrays, raw |
448 |
|
|
columns last. |
449 |
|
|
|
450 |
|
|
The (JSON) type of each column depends on the column itself, and can vary |
451 |
|
|
between rows. |
452 |
|
|
|
453 |
|
|
=over 4 |
454 |
|
|
|
455 |
|
|
=item valid columns for "device" query |
456 |
|
|
|
457 |
|
|
vlanname, port_pktcount, linkduplex, port_mac, device_log_end, |
458 |
|
|
port_errorcount, vtpdomain, switch_ip, device_log_start, |
459 |
|
|
linkstatus, linkspeed, device_mac, history_device, linkadminduplex, |
460 |
|
|
ifname, device_comment, device_notes, vlan, device_dnsname, |
461 |
|
|
ifalias, switch_uid, ifdescr, linkadminstatus, |
462 |
|
|
port_error_percentage, device_ip |
463 |
|
|
|
464 |
|
|
=item valid columns for "switch" query |
465 |
|
|
|
466 |
|
|
number_ports, switch_action, switch_syslocation, |
467 |
|
|
free_ports_percentage, switch_sysservices, switch_dnsname, |
468 |
|
|
history_switch, switch_log_end, switch_pollduration, switch_model, |
469 |
|
|
available_ports_percentage, switch_comment, ports_lastchange, |
470 |
|
|
switch_ip, switch_sysdescr, switch_notes, available_ports, |
471 |
|
|
poe_ports, switch_log_start, switch_uid, switch, free_ports |
472 |
|
|
|
473 |
|
|
=back |
474 |
|
|
|
475 |
|
|
Example: |
476 |
|
|
|
477 |
|
|
> [1, "realm_query", "5100005442", "device", |
478 |
|
|
["switch_uid", "device_ip"], |
479 |
|
|
["device_mac"], |
480 |
|
|
{ "switch_uid" : "switch03%" }] |
481 |
|
|
< [1,1,[["switch03.ibm.de","192.168.40.11","\u00000B\u0006D^"],... |
482 |
|
|
|
483 |
|
|
=item valid columns for "switch_detail" view |
484 |
|
|
|
485 |
|
|
port_pktcount, history_port, linkduplex, port_mac, port_comment, |
486 |
|
|
port_log_start, port_errorcount, port_log_end, |
487 |
|
|
detected_devices_current, linkstatus, linkspeed, linkadminduplex, |
488 |
|
|
ifname, port_action, poe_power, ifalias, switch_uid, poe_status, switch, |
489 |
|
|
ifdescr, linkadminstatus, port_error_percentage |
490 |
|
|
|
491 |
|
|
Example: |
492 |
|
|
|
493 |
|
|
> [5, "realm_query", "5100005442", "switch_detail", |
494 |
|
|
["ifname"], [], |
495 |
|
|
{ "switch" : 27 }] |
496 |
|
|
< [5,1,[["Fa0/11"],["Fa0/21"], ... ,["Fa0/5"]]] |
497 |
|
|
|
498 |
|
|
=item "user_view_info" - return the available views list |
499 |
|
|
|
500 |
|
|
This request returns the report views list for the logged-in user. |
501 |
|
|
|
502 |
|
|
> [<id>, "user_view_info", [<field-list>], [<type-list>]] |
503 |
|
|
< [<id>, 1, [ [<fields>, ...], ...]] |
504 |
|
|
|
505 |
|
|
Valid fields are C<name> and C<gid> and valid types are C<switch>, |
506 |
|
|
C<port> and C<device>. The reply will contains an array for each view. |
507 |
|
|
|
508 |
|
|
Example: |
509 |
|
|
|
510 |
|
|
> [1, "user_view_info", ["gid", "name"]] |
511 |
|
|
< [1,1,[["107374182462","Ports:Default"], |
512 |
|
|
["94489280669","Ports:Multiple Devices on Port"], |
513 |
|
|
["107374182460","End Devices:Default"], |
514 |
|
|
["3865500631171226","End Devices:test"], |
515 |
|
|
["3865500631171236","End Devices:tns04"]]] |
516 |
|
|
|
517 |
|
|
=item "realm_view" - query database with given view in a given realm |
518 |
|
|
|
519 |
|
|
This request returns the database entries for the given view and the realm. |
520 |
|
|
|
521 |
|
|
> [<id>, "realm_view", <realm-gid>, <view-gid>] |
522 |
|
|
< [<id>, 1,[ [<result-data>]]] |
523 |
|
|
|
524 |
|
|
Valid view gid should be given followed by a valid realm gid. |
525 |
|
|
The reply will contain the results from database query and one array per |
526 |
|
|
database row. |
527 |
|
|
|
528 |
|
|
Example: |
529 |
|
|
|
530 |
|
|
> [1, "realm_view", "64424509927", "107374182461"] |
531 |
|
|
< [1,1,[["tnsw04.uk.internal","S","26","15","15","58","0","2009-12-08 12:17:00", |
532 |
|
|
"2009-12-08 12:17:00",null],["tnsw05.uk.internal","S","26","20","20" |
533 |
|
|
,"77","0","2009-12-08 12:17:00","2009-12-08 12:17:00",null]]] |
534 |
|
|
|
535 |
|
|
=item "realm_seed_list" - return the seed list |
536 |
|
|
|
537 |
|
|
This request returns the seed list for the given realm. |
538 |
|
|
|
539 |
|
|
> [<id>, "realm_seed_list", <realm-gid>] |
540 |
|
|
< [<id>, 1, [ [<ip>, <flags>]... ]] |
541 |
|
|
|
542 |
|
|
The reply contains an array with all configured seed devices. Each device |
543 |
|
|
is represented by an array with the IP address in textual form and a flags |
544 |
|
|
bitset. The only defined bit value (not number) is C<2>, which indicates a |
545 |
|
|
manually-added seed entry. |
546 |
|
|
|
547 |
|
|
Example: |
548 |
|
|
|
549 |
|
|
> [1, "realm_seed_list", "5100005442"] |
550 |
|
|
< [1,1,[["192.168.40.11",0],["192.168.40.1",2]]] |
551 |
|
|
|
552 |
|
|
=item "realm_seed_list_modify" - add/remove seed list entries |
553 |
|
|
|
554 |
|
|
This request modifies the seed list for a realm. |
555 |
|
|
|
556 |
|
|
> [<id>, "realm_seed_list_modify", <realm-gid>, [<delete-ip>...], [<add-ip>...>]] |
557 |
|
|
< [<id>, 1] |
558 |
|
|
|
559 |
|
|
The two arrays after the realm-gid specify the IP addresses (in textual |
560 |
|
|
form) of seed entries to remove, followed by a list of IP addresses to be |
561 |
|
|
added afterwards. Newly added IP addresses will have the manual flag set on them. |
562 |
|
|
|
563 |
|
|
Example: set the manually-added flag on 10.0.0.5, or add it if it didn't |
564 |
|
|
exist yet. |
565 |
|
|
|
566 |
|
|
> [1, "realm_seed_list_modify", "5100005442", ["10.0.0.5"], ["10.0.0.5"]] |
567 |
|
|
< [1,1] |
568 |
|
|
|
569 |
|
|
=item "realm_snmp_credential_list" - list snmp credentials |
570 |
|
|
|
571 |
|
|
This request returns the snmp credentials for the given realm. |
572 |
|
|
|
573 |
|
|
> [<id>, "realm_snmp_credential_list", <realm-gid>] |
574 |
|
|
< [<id>, 1, [ [<subnet>, <bits>, [ 2, [<community>...], [3, <v3 settings>] ], <flags>]... ]] |
575 |
|
|
|
576 |
|
|
The reply contains an array with all configured snmp credentials, one per |
577 |
|
|
subnet. Each snmp credential will contain the subnet address in textual |
578 |
|
|
form, the leading number of significant bits in the subnet (0..32 for |
579 |
|
|
IPv4, 0..128 for IPv6), an array per snmp v2 and v3 settings and a flags bitset |
580 |
|
|
(bit value C<1> means it is an include, otherwise it is an exclude). |
581 |
|
|
v2 array starts with bit value C<2> means it is version v2 and followed by an array |
582 |
|
|
of community strings. v3 array starts with bit value C<3> means it is version v3 and |
583 |
|
|
followed by v3 user name, authentication password, privacy password, authentication |
584 |
|
|
algorithm and privacy algorithm. |
585 |
|
|
|
586 |
|
|
Example: |
587 |
|
|
|
588 |
|
|
> [1, "realm_snmp_credential_list", "5100005442"] |
589 |
|
|
< [1,1,[ ["10.1.0.0",16,[[2,["test"]], [3,"authPrivUser","authpass","privpass","md5","aes"]],1] ]] |
590 |
|
|
|
591 |
|
|
=item "realm_snmp_credential_list_modify" - modify snmp credentials |
592 |
|
|
|
593 |
|
|
Removes and/or adds snmp credential entries. |
594 |
|
|
|
595 |
|
|
> [<id>, "realm_snmp_credential_list_modify", <realm-gid>, [<remove-subnet>], [<add-subnet>...]] |
596 |
|
|
< [<id>, 1] |
597 |
|
|
|
598 |
|
|
The two arrays after the realm-gid specify a list of subnet addresses to |
599 |
|
|
remove (only exact matches wil be removed) and a list of subnet-entries to |
600 |
|
|
be added afterwards. Each entry in the <add-subnet> list follows the same |
601 |
|
|
format as returned by C<realm_snmp_credentials>. |
602 |
|
|
|
603 |
|
|
Example: |
604 |
|
|
> [1, "realm_snmp_credential_list_modify", "5100005442", [ ["10.0.0.0", 8], ["11.1.1.0", 24] ], |
605 |
|
|
[ ["192.168.240.0", 24, [2, ["w0rld", "peace"], [3, "noAuthUser"]], 1] ]] |
606 |
|
|
< [1, 1] |
607 |
|
|
|
608 |
|
|
=item "realm_device_assignment_list" - list all assignable devices for a realm |
609 |
|
|
|
610 |
|
|
This request returns all assignable devices. |
611 |
|
|
|
612 |
|
|
> [<id>, "realm_device_assignment", <realm-gid>] |
613 |
|
|
< [<id>, 1, [ [<ip>, <poller-gid>] ]] |
614 |
|
|
|
615 |
|
|
The reply contains an array with all assignable devices in a realm. Each |
616 |
|
|
device entry will contain the device IP address in textual form, and |
617 |
|
|
the gid of the poller it is assigned to, or C<null> if the device isn't |
618 |
|
|
currently assigned. |
619 |
|
|
|
620 |
|
|
Example: |
621 |
|
|
|
622 |
|
|
> [1, "realm_device_assignment_list", "64424509927"] |
623 |
|
|
< [1,1,[ ["192.168.71.21",null],["192.168.75.2",null],["1.1.1.1",64424509930],["5.5.5.5",64424509930]] ] |
624 |
|
|
|
625 |
|
|
=item "realm_device_assign" - assign a device to a poller |
626 |
|
|
|
627 |
|
|
Assigns or unassigns a device, or all devices. |
628 |
|
|
|
629 |
|
|
> [<id>, "realm_device_assign", <realm-gid>] |
630 |
|
|
< [<id>, 1] |
631 |
|
|
|
632 |
|
|
> [<id>, "realm_device_assign", <realm-gid>, [<device-ip>, <poller-gid>]] |
633 |
|
|
< [<id>, 1] |
634 |
|
|
|
635 |
|
|
If only a realm-gid is specified and device and poller-gid are missing, |
636 |
|
|
then all devices get auto-assigned to pollers, if possible. |
637 |
|
|
|
638 |
|
|
Otherwise, the specified device will be assigned to the specified |
639 |
|
|
C<poller-gid>, or unassigned if C<poller-gid> is C<null>. |
640 |
|
|
|
641 |
|
|
Example: |
642 |
|
|
|
643 |
|
|
> [1, "realm_device_assign", "64424509927"] |
644 |
|
|
< [1, 1] |
645 |
|
|
|
646 |
|
|
> [1, "realm_device_assign", "64424509927", ["1.1.1.1", null]] |
647 |
|
|
< [1, 1] |
648 |
|
|
|
649 |
|
|
> [1, "realm_device_assign", "64424509927", ["1.1.1.1", "64424509930"]] |
650 |
|
|
< [1, 1] |
651 |
|
|
|
652 |
|
|
=item "realm_advanced_settings" - list advanced settings of a given realm |
653 |
|
|
|
654 |
|
|
This request returns all/specific properties and their values. |
655 |
|
|
|
656 |
|
|
> [<id>, "realm_advanced_settings", <realm-gid>, [<property>,...]] |
657 |
|
|
< [<id>, 1, [[<property>, <value>]...]] |
658 |
|
|
|
659 |
|
|
If only the realm-gid is specified then all the properties and their values returned. |
660 |
|
|
|
661 |
|
|
valid properties are |
662 |
|
|
|
663 |
|
|
block_port_macs, stp_enabled, cdp_enabled, lldp_enabled |
664 |
|
|
|
665 |
|
|
Example: |
666 |
|
|
|
667 |
|
|
> [1, "realm_advanced_settings", "64424509927", ["cdp_enabled"]] |
668 |
|
|
< [1,1,[["cdp_enabled","1"]]] |
669 |
|
|
|
670 |
|
|
=item "realm_advanced_settings_modify" - modify advanced settings of a given realm |
671 |
|
|
|
672 |
|
|
This request modifies advanced settings of a given realm-gid. |
673 |
|
|
|
674 |
|
|
> [<id>, "realm_advanced_settings_modify", <realm-gid>, [[<property>, <value>]...]] |
675 |
|
|
< [<id>, 1] |
676 |
|
|
|
677 |
|
|
> [<id>, "realm_advanced_settings_modify", <realm-gid>, [[<property>, [<delete-list>], [<add-list>]]]] |
678 |
|
|
< [<id>, 1] |
679 |
|
|
|
680 |
|
|
realm-gid followed by a array of property and value pairs. one array for each property |
681 |
|
|
and value pair. |
682 |
|
|
|
683 |
|
|
block_port_macs property expects two arrays in place of value. First array is a list of |
684 |
|
|
macs needs to be deleted from port exclusion list and second array is a list of |
685 |
|
|
macs needs to be added into port exclusion list. MAC addresses should be in the following |
686 |
|
|
format "AA:BB:CC:DD:EE:FF". |
687 |
|
|
When no array given for block_port_macs property all the macs from port exclusion list |
688 |
|
|
will get deleted. |
689 |
|
|
|
690 |
|
|
Example: |
691 |
|
|
|
692 |
|
|
> [1, "realm_advanced_settings_modify", "64424509927", [["cdp_enabled", "0"]]] |
693 |
|
|
< [1, 1] |
694 |
|
|
|
695 |
|
|
> [1, "realm_advanced_settings_modify", "64424509927", [["block_port_macs", |
696 |
|
|
["11:00:0a:0b:11:22"], ["0a:11:22:44:0e:0b"]]]] |
697 |
|
|
< [1, 1] |
698 |
|
|
|
699 |
|
|
=item "poller_info" - - information about pollers |
700 |
|
|
|
701 |
|
|
> [<id>, "poller_info", [<fields...>], [<pollers...>]] |
702 |
|
|
< [<id>, 1, [ [<fields...>]... ]] |
703 |
|
|
|
704 |
|
|
Example: |
705 |
|
|
|
706 |
|
|
> [1, "poller_info", ["gid", "name", "description", "hostname"]] |
707 |
|
|
< [1,1,[["64424509930","localhost","localhost","127.0.0.1"]]] |
708 |
|
|
|
709 |
|
|
|
710 |
|
|
Requests information about the given pollers (or all pollers if specified as |
711 |
|
|
C<null>). The following fields can be requested, and their contents will be |
712 |
|
|
returned in the order specified in the C<fields> array: |
713 |
|
|
|
714 |
|
|
=over 4 |
715 |
|
|
|
716 |
|
|
=item gid - the gid (id value) identifying the poller |
717 |
|
|
|
718 |
|
|
=item name - the user-specified name of the poller |
719 |
|
|
|
720 |
|
|
=item description - the user-specified description for this poller |
721 |
|
|
|
722 |
|
|
=item hostname - hostname/ip of this poller |
723 |
|
|
|
724 |
|
|
=item dns_max_outstanding - maximum number of dns queries for this poller |
725 |
|
|
|
726 |
|
|
=back |
727 |
|
|
|
728 |
|
|
=item "poller_modify" - adds and/or deletes pollers |
729 |
|
|
|
730 |
|
|
This request adds and/or deletes given pollers. |
731 |
|
|
|
732 |
|
|
> [<id>, "poller_modify", <realm-gid>, [<delete-gid>, ...], |
733 |
|
|
[[<name>, <description>, <hostname>, <secret>], ...]] |
734 |
|
|
< [<id>, 1] |
735 |
|
|
|
736 |
|
|
Two arrays followed by a realm gid. First array is a list of poller gids |
737 |
|
|
needs to be deleted. Second array is a list of pollers needs to be added. |
738 |
|
|
An array per poller should contain poller name, description, hostname and |
739 |
|
|
secret password. |
740 |
|
|
|
741 |
|
|
Example: |
742 |
|
|
|
743 |
|
|
> [1, "poller_modify", "385611201213", ["98456723211"], [["test1", |
744 |
|
|
"Test poller", "127.0.0.1", "test"]]] |
745 |
|
|
< [1, 1] |
746 |
|
|
|
747 |
|
|
=item "poller_info_modify - edits the given poller |
748 |
|
|
|
749 |
|
|
This request edits the given poller with new values. |
750 |
|
|
|
751 |
|
|
> [<id>, "poller_info_modify", <poller-gid>, {<prop>:<value>,...}] |
752 |
|
|
< [<id>, 1] |
753 |
|
|
|
754 |
|
|
A property hash followed by a poller gid. Keys expected in the hash |
755 |
|
|
are name, description, hostname, secret and dns_max_outstanding. |
756 |
|
|
|
757 |
|
|
Example: |
758 |
|
|
|
759 |
|
|
> [1, "poller_info_modify", "6789345621", {"name":"test1", |
760 |
|
|
"secret":"test123", "hostname":"localhost", |
761 |
|
|
"dns_max_outstanding":"65"}] |
762 |
|
|
< [1, 1] |
763 |
|
|
|
764 |
|
|
=item "poller_subnet_list" - list subnets attached to a given poller |
765 |
|
|
|
766 |
|
|
This request returns all subnets attached to a given poller. |
767 |
|
|
|
768 |
|
|
> [<id>, "poller_subnet_list", <poller-gid>] |
769 |
|
|
< [<id>, 1, [ [<subnet>, <bits>, <ping-limit>, <flags>]... ]] |
770 |
|
|
|
771 |
|
|
The reply contains an array with all configured subnets. Each subnet |
772 |
|
|
will contain the subnet address in textual form, the leading number of |
773 |
|
|
significant bits in the subnet (0..32 for IPv4, 0..128 for IPv6), a ping |
774 |
|
|
limit (in kbit/s) and a flags value (bit value C<1> indicates whether the |
775 |
|
|
subnet is exclided (C<0>) or included (C<1>), bit value C<2> indicates |
776 |
|
|
whether pings are enabled (C<2>) or not). |
777 |
|
|
|
778 |
|
|
Example: |
779 |
|
|
|
780 |
|
|
> [1, "poller_subnet_list", "64424509930"] |
781 |
|
|
< [1,1,[["1.1.1.1",32,1000,1,2],["10.1.1.1",32,1000,0,0]]] |
782 |
|
|
|
783 |
|
|
=item "poller_subnet_list_modify" - modify subnets of a poller |
784 |
|
|
|
785 |
|
|
Removes and/or adds subnet entries. |
786 |
|
|
|
787 |
|
|
> [<id>, "poller_subnet_list_modify", <poller-gid>, [<remove-subnet>], [<add-subnet>...]] |
788 |
|
|
< [<id>, 1] |
789 |
|
|
|
790 |
|
|
The two arrays after the poller-gid specify a list of subnet addresses to |
791 |
|
|
remove (only exact matches wil be removed) and a list of subnet-entries to |
792 |
|
|
be added afterwards. Each entry in the <add-subnet> list follows the same |
793 |
|
|
format as returned by C<poller_subnet_list>. |
794 |
|
|
|
795 |
|
|
Example: |
796 |
|
|
|
797 |
|
|
> [ 1, "poller_subnet_list_modify", "64424509930",[["1.1.1.1",32,1000,1,2], |
798 |
|
|
["10.1.1.1",32,1000,0,0]], [["192.168.0.0", 16, 1200, 1,2]] ] |
799 |
|
|
< [1, 1] |
800 |
|
|
|
801 |
|
|
=item "global_settings" - list global settings |
802 |
|
|
|
803 |
|
|
This request returns all global settings or specific settings. |
804 |
|
|
|
805 |
|
|
> [<id>, "global_settings"] |
806 |
|
|
< [<id>, 1, [ [<property>, <value>]... ]] |
807 |
|
|
|
808 |
|
|
The reply contains an array with all configured properties and values. Each property |
809 |
|
|
and value will be in textual form. |
810 |
|
|
|
811 |
|
|
valid properties are |
812 |
|
|
|
813 |
|
|
normalization_algorithm, snmp_parallel_requests, session_timeout, snmp_retries, |
814 |
|
|
agni_verbose, domain, snmp_timeout, smtp_server, skip_access_points, max_history_length, |
815 |
|
|
smtp_user, autoassign, skip_cisco_phones, skip_mitel_phones, max_log_length |
816 |
|
|
|
817 |
|
|
Example: |
818 |
|
|
|
819 |
|
|
> [1, "global_settings"] |
820 |
|
|
< [1,1,[["normalization_algorithm","loopback highest-ip lowest-ip"], |
821 |
|
|
["snmp_parallel_requests","10"],["session_timeout","86400"],["snmp_retries","5"], |
822 |
|
|
["agni_verbose",null],["domain",""],["snmp_timeout","4"],["smtp_server",""], |
823 |
|
|
["skip_access_points","1"],["max_history_length","0"],["smtp_user",""],["autoassign","1"],["skip_cisco_phones","1"]]] |
824 |
|
|
|
825 |
|
|
> [1, "global_settings", ["normalization_algorithm", "session_timeout"]] |
826 |
|
|
< [1,1,[["normalization_algorithm","loopback highest-ip lowest-ip"],["session_timeout","86400"]]] |
827 |
|
|
|
828 |
|
|
=item "global_settings_modify" - modify global settings |
829 |
|
|
|
830 |
|
|
This request modifies global settings. Each property modified with a new value given. |
831 |
|
|
|
832 |
|
|
> [<id>, "global_settings_modify", [ [<property>, <value>]... ]] |
833 |
|
|
< [<id>, 1] |
834 |
|
|
|
835 |
|
|
one array for each property and value pair. Properties and values should be in |
836 |
|
|
textual format. |
837 |
|
|
|
838 |
|
|
valid properties are |
839 |
|
|
|
840 |
|
|
normalization_algorithm, snmp_parallel_requests, session_timeout, snmp_retries, |
841 |
|
|
agni_verbose, domain, snmp_timeout, smtp_server, skip_access_points, max_history_length, |
842 |
|
|
smtp_user, autoassign, skip_cisco_phones, max_log_length, skip_mitel_phones, smtp_pass |
843 |
|
|
|
844 |
|
|
Example: |
845 |
|
|
|
846 |
|
|
> [1, "global_settings_modify", [["snmp_parallel_requests", "15"]]] |
847 |
|
|
< [1, 1] |
848 |
|
|
|
849 |
|
|
=item "advanced_settings" - list advanced settings |
850 |
|
|
|
851 |
|
|
This request returns all advanced settings or specific settings. |
852 |
|
|
|
853 |
|
|
> [<id>, "advanced_settings"] |
854 |
|
|
< [<id>, 1, [ [<property>, <value>]... ]] |
855 |
|
|
|
856 |
|
|
The reply contains an array with all configured properties and values. Each property |
857 |
|
|
and value will be in textual form. |
858 |
|
|
|
859 |
|
|
valid properties are |
860 |
|
|
|
861 |
|
|
max_parallel_jobs, max_debug_scans, debug_level |
862 |
|
|
|
863 |
|
|
Example: |
864 |
|
|
|
865 |
|
|
> [1, "advanced_settings", ["max_parallel_jobs"]] |
866 |
|
|
< [1,1,[["max_parallel_jobs","1000"]]] |
867 |
|
|
|
868 |
|
|
=item "advanced_settings_modify" - modify advanced settings |
869 |
|
|
|
870 |
|
|
This request modifies advanced settings. Each property modified with a new value given. |
871 |
|
|
|
872 |
|
|
> [<id>, "advanced_settings_modify", [ [<property>, <value>]...]] |
873 |
|
|
< [<id>, 1] |
874 |
|
|
|
875 |
|
|
one array for each property and value pair. Properties and values should be in |
876 |
|
|
textual format. |
877 |
|
|
|
878 |
|
|
Example: |
879 |
|
|
|
880 |
|
|
> [1, "advanced_settings_modify", [ ["max_parallel_jobs", "900"]]] |
881 |
|
|
< [1, 1] |
882 |
|
|
|
883 |
|
|
|
884 |
|
|
=item "security_misc_settings" - lists misellenous security settings |
885 |
|
|
|
886 |
|
|
This request returns all misellenous settings or specific settings. |
887 |
|
|
|
888 |
|
|
> [<id>, "security_misc_settings", [<property, ... ]] |
889 |
|
|
< [<id>, 1, [<value>, ...] ] |
890 |
|
|
|
891 |
|
|
valid properties are |
892 |
|
|
|
893 |
|
|
login_banner enable_login_banner |
894 |
|
|
|
895 |
|
|
Example: |
896 |
|
|
|
897 |
|
|
> [1, "security_misc_settings", ["login_banner"]] |
898 |
|
|
< [1,1,["This system is the property of ..."]] |
899 |
|
|
|
900 |
|
|
=item "security_misc_settings_modify" - modifies given misellenous property |
901 |
|
|
|
902 |
|
|
This request modifies given property with the given new value. |
903 |
|
|
|
904 |
|
|
> [<id>, "security_misc_settings_modify", {<property> : <value>, ... }] |
905 |
|
|
< [<id>, 1] |
906 |
|
|
|
907 |
|
|
Example: |
908 |
|
|
|
909 |
|
|
> [1, "security_misc_settings_modify", {"login_banner" : "Its My Box."}] |
910 |
|
|
< [1, 1] |
911 |
|
|
|
912 |
|
|
=item "security_certificate_list" - lists available certificates |
913 |
|
|
|
914 |
|
|
This request returns all or given properties of all certificates. |
915 |
|
|
|
916 |
|
|
> [<id>, "security_certificate_list", [<property>, ...] ] |
917 |
|
|
< [<id>, 1, [ [<value>, ...] , ... ] ] |
918 |
|
|
|
919 |
|
|
Valid properties are |
920 |
|
|
|
921 |
|
|
name certificate |
922 |
|
|
|
923 |
|
|
Example: |
924 |
|
|
|
925 |
|
|
> [1, "security_certificate_list"] |
926 |
|
|
< [1, 1, [["System Default",""],["custom", ,"-----BEGIN RSA PRIVATE KEY..."]]] |
927 |
|
|
|
928 |
|
|
=item "security_certificate_list_modify" - adds/deletes given certificates |
929 |
|
|
|
930 |
|
|
This request deletes and adds given certificates. |
931 |
|
|
|
932 |
|
|
> [<id>, "security_certificate_list_modify", [<delete-list>], [[<name>, <certificate>], ...]] |
933 |
|
|
< [<id>, 1] |
934 |
|
|
|
935 |
|
|
delete-list contains list of certificate names. |
936 |
|
|
add-list should have a name and certificate one array per certificate. |
937 |
|
|
|
938 |
|
|
Example: |
939 |
|
|
|
940 |
|
|
> [1, "security_certificate_list_modify", ["old_custom"], [["new_custom", "-----BEGIN RSA PRIVATE KEY..."] |
941 |
|
|
]] |
942 |
|
|
< [1, 1] |
943 |
|
|
|
944 |
|
|
=item "security_certificate_assignment_list" - lists all assignable certificates |
945 |
|
|
|
946 |
|
|
This request returns all certificate name and their current status. |
947 |
|
|
one array per certicate will be used. current status shows whether it is assigned |
948 |
|
|
to C<apache> or C<api> or C<null> for not in use. |
949 |
|
|
|
950 |
|
|
> [<id>, "security_certificate_assignment_list"] |
951 |
|
|
< [<id>, 1, [ [<name>, <status>], ... ]] |
952 |
|
|
|
953 |
|
|
Example: |
954 |
|
|
|
955 |
|
|
> [1, "security_certificate_assignment_list"] |
956 |
|
|
> [1,1,[["System Default","apache"],["System Default","api"],["custome",null]]] |
957 |
|
|
|
958 |
|
|
=item "security_certificate_assign" - assigns given certificate to api or apache |
959 |
|
|
|
960 |
|
|
This request assigns given certificate to apache or api. |
961 |
|
|
|
962 |
|
|
> [<id>, "security_certificate_assign", [ [<name>, <assign>], ...] ] |
963 |
|
|
< [<id>, 1] |
964 |
|
|
|
965 |
|
|
Example: |
966 |
|
|
|
967 |
|
|
> [1, "security_certificate_assign", [["custom", "apache"], ["custom", "api"]]] |
968 |
|
|
< [1, 1] |
969 |
|
|
|
970 |
|
|
=item "security_authentication_method_list" - lists authentication methods and settings |
971 |
|
|
|
972 |
|
|
This request returns all or specified properties of all or specified authentication method. |
973 |
|
|
First array contains the list of properties and the second array contains the list of gids |
974 |
|
|
of methods. Result array will have one array per authentication method. |
975 |
|
|
|
976 |
|
|
Valid properties are |
977 |
|
|
|
978 |
|
|
name gid inuse settings |
979 |
|
|
|
980 |
|
|
> [<id>, "security_authentication_method_list", [<properties>, ...], [<method-gid>, ...]] |
981 |
|
|
< [<id>, 1, [ [<value>, ...], ...]] |
982 |
|
|
|
983 |
|
|
Example: |
984 |
|
|
|
985 |
|
|
> [1, "security_authentication_method_list", ["name"], ["90194313753", "90194313603"]] |
986 |
|
|
< [1,1,[["RADIUS"],["Active Directory (LDAPS)"]]] |
987 |
|
|
|
988 |
|
|
=item "security_authentication_modify" - modifies given authentication methods |
989 |
|
|
|
990 |
|
|
This request edits given authentication method. |
991 |
|
|
First argument is the authentication method gid. |
992 |
|
|
All new values should be mentioned in a hash. |
993 |
|
|
|
994 |
|
|
Valid properties are |
995 |
|
|
|
996 |
|
|
inuse server secret csecret domain ctrls certificate |
997 |
|
|
|
998 |
|
|
bit value C<inuse> will activate/inactivate the given authentication method. |
999 |
|
|
C<server> is the RADIUS server for RADIUS authentication method. |
1000 |
|
|
C<secret> and C<csecret> are secret password and confirm secret password for RADIUS server. |
1001 |
|
|
C<domain> is the domain name for LDAP and LDAPS authentication methods. |
1002 |
|
|
C<ctrls> is the array of delete and add lists of domain controls. |
1003 |
|
|
C<certificate> is the valid certificate name for LDAPS authentication method. |
1004 |
|
|
C<timeout> is the value in seconds to be used when communicating with Active Directory servers. |
1005 |
|
|
|
1006 |
|
|
> [<id>, "security_authentication_modify", <method-gid>, {<property> : <value>,... }] |
1007 |
|
|
< [<id>, 1] |
1008 |
|
|
|
1009 |
|
|
Example: |
1010 |
|
|
|
1011 |
|
|
> [1, "security_authentication_modify", "90194313753", {"inuse" : 1, "server" : "4test"}] |
1012 |
|
|
< [1, 1] |
1013 |
|
|
|
1014 |
|
|
> [1, "security_authentication_modify", "90194313603", {"certificate" : "custom", "domain" : "new" |
1015 |
|
|
"ctrls" : [ ["10.1.50.1"], ["10.1.50.2"] ]}] |
1016 |
|
|
< [1, 1] |
1017 |
|
|
|
1018 |
|
|
=item "group_info" - lists group information |
1019 |
|
|
|
1020 |
|
|
This request returns all groups or specific groups. The request returns all |
1021 |
|
|
fields or specific fields. |
1022 |
|
|
|
1023 |
|
|
> [<id>, "group_info", [<field1>, <field2>, ...], [<group-gid>, ...]] |
1024 |
|
|
< [<id>, 1, [ [<value>, <value>, ...] , ...] |
1025 |
|
|
|
1026 |
|
|
The reply contains an array for each group with specified field values or all. |
1027 |
|
|
|
1028 |
|
|
Example: |
1029 |
|
|
|
1030 |
|
|
> [1, "group_info", ["name"]] |
1031 |
|
|
< [1,1,[["helpme"],["Network Administrator"],["Network Operator"],["Super Admin"]]] |
1032 |
|
|
|
1033 |
|
|
=item "group_modify" - adds and/or deletes groups |
1034 |
|
|
|
1035 |
|
|
This request adds and/or deletes given groups. |
1036 |
|
|
|
1037 |
|
|
> [<id>, "group_modify", [<delete-gid>, ...], [[<name>, <description>], ...]] |
1038 |
|
|
< [<id>, 1] |
1039 |
|
|
|
1040 |
|
|
Two arrays expected as input. First array is a list of group gids needs to be deleted. |
1041 |
|
|
Second array is a list of groups needs to be added. An array per group should contain |
1042 |
|
|
group name and description. |
1043 |
|
|
|
1044 |
|
|
Example: |
1045 |
|
|
|
1046 |
|
|
> [1, "group_modify", ["9845672231"], [["test1", "Test group"]]] |
1047 |
|
|
< [1, 1] |
1048 |
|
|
|
1049 |
|
|
=item "group_settings" - lists permissions for a given group |
1050 |
|
|
|
1051 |
|
|
> [<id>, "group_settings", <group-gid>, [<role>, <role>, ...], [<realm-gid>, ...]] |
1052 |
|
|
< [<id>, 1, [[[<system-role>, <permission>], ...], |
1053 |
|
|
[[<realm-gid>, [[<realm-role>, <permission>], ...]], ...]]] |
1054 |
|
|
|
1055 |
|
|
The input should have a valid group gid in textual format. Two arrays followed by group gid |
1056 |
|
|
are list of roles and list of realm gids. These two arrays are optional. |
1057 |
|
|
The result contains two arrays. First array is for system specific roles. One array per role. |
1058 |
|
|
Second array is for realm specific roles. One array per realm. First element of the array is |
1059 |
|
|
realm-gid in textual format followed by an array of realm specific roles and their permission. |
1060 |
|
|
Permission will be referred in bit value. bit value C<0> means NO Access, C<1> means |
1061 |
|
|
Read Access and C<2> means Read/Write Access. |
1062 |
|
|
|
1063 |
|
|
Example: |
1064 |
|
|
|
1065 |
|
|
> [1, "group_settings", "98784248728"] |
1066 |
|
|
< [1,1,[[["API",2],["Add Realms",2],["Advanced Settings",1],["Global Settings",2]] |
1067 |
|
|
,[["3865500631171652",[["Advanced Realm Settings",0],["Assign Devices",0]]]]]] |
1068 |
|
|
|
1069 |
|
|
> [1, "group_settings", "98784248728", ["Add Realms", "Assign Devices"]] |
1070 |
|
|
< [1,1,[[["Add Realms",2]],[["3865500631171652",[["Assign Devices",0]]], |
1071 |
|
|
["3865500631171517",[["Assign Devices",0]]]]]] |
1072 |
|
|
|
1073 |
|
|
|
1074 |
|
|
=item "group_settings_modify" - edits group properties and permissions |
1075 |
|
|
|
1076 |
|
|
> [<id>, "group_settings_modify", <group-gid> |
1077 |
|
|
, {"name":<group-name>, "description":<group description>} |
1078 |
|
|
, [[<system-role>, <permission>], ...], [[<realm-gid>, |
1079 |
|
|
[[<realm-role>, <permission>], ...]], ...] ] |
1080 |
|
|
< [<id>, 1] |
1081 |
|
|
|
1082 |
|
|
The input should have a valid group gid. A property hash followed by the group gid. |
1083 |
|
|
The values of keys C<name> and C<description> are new group name and description. |
1084 |
|
|
Two arrays followed by hash. First array is for system specific roles. Format of the |
1085 |
|
|
array is same as output of C<group_settings> query. Second array is for realm specific roles. |
1086 |
|
|
One array per realm. Format of this array is same as output of C<group_settings> query. |
1087 |
|
|
|
1088 |
|
|
valid system specific roles are |
1089 |
|
|
|
1090 |
|
|
"API", "Add Realms", "Advanced Settings", "Global Settings", "Group Management", "License", |
1091 |
|
|
"Schedule Backup", "Security Settings", "System Utilities", "User Management", "View Log" |
1092 |
|
|
|
1093 |
|
|
valid realm specific roles are |
1094 |
|
|
|
1095 |
|
|
"Advanced Realm Settings", "Assign Devices", "Discovery Realm Settings", "Views", |
1096 |
|
|
"Plugins", "Poller Settings", "Schedule Discovery","Schedule Poll","Schedule Report" |
1097 |
|
|
,"Schedule Sync" |
1098 |
|
|
|
1099 |
|
|
Example: |
1100 |
|
|
|
1101 |
|
|
> [1, "group_settings_modify", "98784248723", {"name":"TEST"}, |
1102 |
|
|
[["Add Realms",0]]], [["386550063117151",[["Poller Setting",1]]]]] |
1103 |
|
|
< [1, 1] |
1104 |
|
|
|
1105 |
|
|
|
1106 |
|
|
> [1, "group_settings_modify", "98784248723", {}, |
1107 |
|
|
[["Add Realms",0],["Global Settings",1]]] |
1108 |
|
|
< [1, 1] |
1109 |
|
|
|
1110 |
|
|
|
1111 |
|
|
=back |
1112 |
|
|
|
1113 |
|
|
=head1 AUTHOR |
1114 |
|
|
|
1115 |
|
|
Marc Lehmann <marc@nethype.de>. |
1116 |
|
|
|