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