| blob | f4140d184a33a2dd43eeae6272d1567316128bfa |
1 .\" $NetBSD: dhcpctl.3,v 1.1.1.3 2014/07/12 11:57:51 spz Exp $
2 .\"
3 .\" -*- nroff -*-
4 .\"
5 .\" Project: DHCP
6 .\" File: dhcpctl.3
7 .\" RCSId: Id: dhcpctl.3,v 1.9 2011/04/25 23:43:16 sar Exp
8 .\"
9 .\" Copyright (c) 2011,2014 by Internet Systems Consortium, Inc. ("ISC")
10 .\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
11 .\" Copyright (c) 2000-2003 by Internet Software Consortium
12 .\" Copyright (c) 2000 Nominum, Inc.
13 .\"
14 .\" Permission to use, copy, modify, and distribute this software for any
15 .\" purpose with or without fee is hereby granted, provided that the above
16 .\" copyright notice and this permission notice appear in all copies.
17 .\"
18 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
19 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
20 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
21 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
22 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
23 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
24 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 .\"
26 .\" Internet Systems Consortium, Inc.
27 .\" 950 Charter Street
28 .\" Redwood City, CA 94063
29 .\" <info@isc.org>
30 .\" https://www.isc.org/
31 .\"
32 .\" Description: dhcpctl man page.
33 .\"
34 .\"
35 .Dd Nov 15, 2000
36 .Dt DHCPCTL 3
37 .Os DHCP 3
38 .ds vT DHCP Programmer's Manual
39 .\"
40 .\"
41 .\"
42 .Sh NAME
43 .Nm dhcpctl_initialize
44 .Nd dhcpctl library initialization.
45 .\"
46 .\"
47 .\"
48 .Sh SYNOPSIS
49 .Fd #include <dhcpctl/dhcpctl.h>
50 .Ft dhcpctl_status
51 .Fo dhcpctl_initialize
52 .Fa void
53 .Fc
54 .\"
55 .Ft dhcpctl_status
56 .Fo dhcpctl_connect
57 .Fa "dhcpctl_handle *cxn"
58 .Fa "const char *host"
59 .Fa "int port"
60 .Fa "dhcpctl_handle auth"
61 .Fc
62 .\"
63 .\"
64 .\"
65 .Ft dhcpctl_status
66 .Fo dhcpctl_wait_for_completion
67 .Fa "dhcpctl_handle object"
68 .Fa "dhcpctl_status *status"
69 .Fc
70 .\"
71 .\"
72 .\"
73 .Ft dhcpctl_status
74 .Fo dhcpctl_get_value
75 .Fa "dhcpctl_data_string *value"
76 .Fa "dhcpctl_handle object"
77 .Fa "const char *name"
78 .Fc
79 .\"
80 .\"
81 .\"
82 .Ft dhcpctl_status
83 .Fo dhcpctl_get_boolean
84 .Fa "int *value"
85 .Fa "dhcpctl_handle object"
86 .Fa "const char *name"
87 .Fc
88 .\"
89 .\"
90 .\"
91 .Ft dhcpctl_status
92 .Fo dhcpctl_set_value
93 .Fa "dhcpctl_handle object"
94 .Fa "dhcpctl_data_string value"
95 .Fa "const char *name"
96 .Fc
97 .\"
98 .\"
99 .\"
100 .Ft dhcpctl_status
101 .Fo dhcpctl_set_string_value
102 .Fa "dhcpctl_handle object"
103 .Fa "const char *value"
104 .Fa "const char *name"
105 .Fc
106 .\"
107 .\"
108 .\"
109 .Ft dhcpctl_status
110 .Fo dhcpctl_set_boolean_value
111 .Fa "dhcpctl_handle object"
112 .Fa "int value"
113 .Fa "const char *name"
114 .Fc
115 .\"
116 .\"
117 .\"
118 .Ft dhcpctl_status
119 .Fo dhcpctl_set_int_value
120 .Fa "dhcpctl_handle object"
121 .Fa "int value"
122 .Fa "const char *name"
123 .Fc
124 .\"
125 .\"
126 .\"
127 .Ft dhcpctl_status
128 .Fo dhcpctl_object_update
129 .Fa "dhcpctl_handle connection"
130 .Fa "dhcpctl_handle object"
131 .Fc
132 .\"
133 .\"
134 .\"
135 .Ft dhcpctl_status
136 .Fo dhcpctl_object_refresh
137 .Fa "dhcpctl_handle connection"
138 .Fa "dhcpctl_handle object"
139 .Fc
140 .\"
141 .\"
142 .\"
143 .Ft dhcpctl_status
144 .Fo dhcpctl_object_remove
145 .Fa "dhcpctl_handle connection"
146 .Fa "dhcpctl_handle object"
147 .Fc
148 .\"
149 .\"
150 .\"
151 .Ft dhcpctl_status
152 .Fo dhcpctl_set_callback
153 .Fa "dhcpctl_handle object"
154 .Fa "void *data"
155 .Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
156 .Fc
157 .\"
158 .\"
159 .\"
160 .Ft dhcpctl_status
161 .Fo dhcpctl_new_authenticator
162 .Fa "dhcpctl_handle *object"
163 .Fa "const char *name"
164 .Fa "const char *algorithm"
165 .Fa "const char *secret"
166 .Fa "unsigned secret_len"
167 .Fc
168 .\"
169 .\"
170 .\"
171 .Ft dhcpctl_status
172 .Fo dhcpctl_new_object
173 .Fa "dhcpctl_handle *object"
174 .Fa "dhcpctl_handle connection"
175 .Fa "const char *object_type"
176 .Fc
177 .\"
178 .\"
179 .\"
180 .Ft dhcpctl_status
181 .Fo dhcpctl_open_object
182 .Fa "dhcpctl_handle object"
183 .Fa "dhcpctl_handle connection"
184 .Fa "int flags"
185 .Fc
186 .\"
187 .\"
188 .\"
189 .Ft isc_result_t
190 .Fo omapi_data_string_new
191 .Fa dhcpctl_data_string *data
192 .Fa unsigned int length
193 .Fa const char *filename,
194 .Fa int lineno
195 .Fc
196 .\"
197 .\"
198 .\"
199 .Ft isc_result_t
200 .Fo dhcpctl_data_string_dereference
201 .Fa "dhcpctl_data_string *"
202 .Fa "const char *"
203 .Fa "int"
204 .Fc
205 .Sh DESCRIPTION
206 The dhcpctl set of functions provide an API that can be used to communicate
207 with and manipulate a running ISC DHCP server. All functions return a value of
208 .Dv isc_result_t .
209 The return values reflects the result of operations to local data
210 structures. If an operation fails on the server for any reason, then the error
211 result will be returned through the
212 second parameter of the
213 .Fn dhcpctl_wait_for_completion
214 call.
215 .\"
216 .\"
217 .\"
218 .Pp
219 .Fn dhcpctl_initialize
220 sets up the data structures the library needs to do its work. This function
221 must be called once before any other.
222 .Pp
223 .Fn dhcpctl_connect
224 opens a connection to the DHCP server at the given host and port. If an
225 authenticator has been created for the connection, then it is given as the 4th
226 argument. On a successful return the address pointed at by the first
227 argument will have a new connection object assigned to it.
228 .Pp
229 For example:
230 .Bd -literal -offset indent
231 s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
232 .Ed
233 .Pp
234 connects to the DHCP server on the localhost via port 7911 (the standard
235 OMAPI port). No authentication is used for the connection.
236 .\"
237 .\"
238 .\"
239 .Pp
240 .Fn dhcpctl_wait_for_completion
241 flushes a pending message to the server and waits for the response. The result
242 of the request as processed on the server is returned via the second
243 parameter.
244 .Bd -literal -offset indent
245 s = dhcpctl_wait_for_completion(cxn, &wv);
246 if (s != ISC_R_SUCCESS)
247 local_failure(s);
248 else if (wv != ISC_R_SUCCESS)
249 server_failure(wc);
250 .Ed
251 .Pp
252 The call to
253 .Fn dhcpctl_wait_for_completion
254 won't return until the remote message processing completes or the connection
255 to the server is lost.
256 .\"
257 .\"
258 .\"
259 .Pp
260 .Fn dhcpctl_get_value
261 extracts a value of an attribute from the handle. The value can be of any
262 length and is treated as a sequence of bytes. The handle must have been
263 created first with
264 .Fn dhcpctl_new_object
265 and opened with
266 .Fn dhcpctl_open_object .
267 The value is returned via the parameter named
268 .Dq value .
269 The last parameter is the name of attribute to retrieve.
270 .Bd -literal -offset indent
271 dhcpctl_data_string value = NULL;
272 dhcpctl_handle lease;
273 time_t thetime;
275 s = dhcpctl_get_value (&value, lease, "ends");
276 assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
277 memcpy(&thetime, value->value, value->len);
278 .Ed
279 .\"
280 .\"
281 .\"
282 .Pp
283 .Fn dhcpctl_get_boolean
284 extracts a boolean valued attribute from the object handle.
285 .\"
286 .\"
287 .\"
288 .Pp
289 The
290 .Fn dhcpctl_set_value ,
291 .Fn dhcpctl_set_string_value ,
292 .Fn dhcpctl_set_boolean_value ,
293 and
294 .Fn dhcpctl_set_int_value
295 functions all set a value on the object handle.
296 .\"
297 .\"
298 .\"
299 .Pp
300 .Fn dhcpctl_object_update
301 function queues a request for
302 all the changes made to the object handle be sent to the remote
303 for processing. The changes made to the attributes on the handle will be
304 applied to remote object if permitted.
305 .\"
306 .\"
307 .\"
308 .Pp
309 .Fn dhcpctl_object_refresh
310 queues up a request for a fresh copy of all the attribute values to be sent
311 from the remote to
312 refresh the values in the local object handle.
313 .\"
314 .\"
315 .\"
316 .Pp
317 .Fn dhcpctl_object_remove
318 queues a request for the removal on the server of the object referenced by the
319 handle.
320 .\"
321 .\"
322 .\"
323 .Pp
324 The
325 .Fn dhcpctl_set_callback
326 function sets up a user-defined function to be called when an event completes
327 on the given object handle. This is needed for asynchronous handling of
328 events, versus the synchronous handling given by
329 .Fn dhcpctl_wait_for_completion .
330 When the function is called the first parameter is the object the event
331 arrived for, the second is the status of the message that was processed, the
332 third is the same value as the second parameter given to
333 .Fn dhcpctl_set_callback .
334 .\"
335 .\"
336 .\"
337 .Pp
338 The
339 .Fn dhcpctl_new_authenticator
340 creates a new authenticator object to be used for signing the messages
341 that cross over the network. The
342 .Dq name ,
343 .Dq algorithm ,
344 and
345 .Dq secret
346 values must all match what the server uses and are defined in its
347 configuration file. The created object is returned through the first parameter
348 and must be used as the 4th parameter to
349 .Fn dhcpctl_connect .
350 Note that the 'secret' value must not be base64 encoded, which is different
351 from how the value appears in the dhcpd.conf file.
352 .\"
353 .\"
354 .\"
355 .Pp
356 .Fn dhcpctl_new_object
357 creates a local handle for an object on the server. The
358 .Dq object_type
359 parameter is the ascii name of the type of object being accessed. e.g.
360 .Qq lease .
361 This function only sets up local data structures, it does not queue any
362 messages
363 to be sent to the remote side,
364 .Fn dhcpctl_open_object
365 does that.
366 .\"
367 .\"
368 .\"
369 .Pp
370 .Fn dhcpctl_open_object
371 builds and queues the request to the remote side. This function is used with
372 handle created via
373 .Fn dhcpctl_new_object .
374 The flags argument is a bit mask with the following values available for
375 setting:
376 .Bl -tag -offset indent -width 20
377 .It DHCPCTL_CREATE
378 if the object does not exist then the remote will create it
379 .It DHCPCTL_UPDATE
380 update the object on the remote side using the
381 attributes already set in the handle.
382 .It DHCPCTL_EXCL
383 return and error if the object exists and DHCPCTL_CREATE
384 was also specified
385 .El
386 .\"
387 .\"
388 .\"
389 .Pp
390 The
391 .Fn omapi_data_string_new
392 function allocates a new
393 .Ft dhcpctl_data_string
394 object. The data string will be large enough to hold
395 .Dq length
396 bytes of data. The
397 .Dq file
398 and
399 .Dq lineno
400 arguments are the source file location the call is made from, typically by
401 using the
402 .Dv __FILE__
403 and
404 .Dv __LINE__
405 macros or the
406 .Dv MDL
407 macro defined in
408 .
409 .\"
410 .\"
411 .\"
412 .Pp
413 .Fn dhcpctl_data_string_dereference
414 deallocates a data string created by
415 .Fn omapi_data_string_new .
416 The memory for the object won't be freed until the last reference is
417 released.
418 .Sh EXAMPLES
419 .Pp
420 The following program will connect to the DHCP server running on the local
421 host and will get the details of the existing lease for IP address
422 10.0.0.101. It will then print out the time the lease is due to expire. Note
423 that most error checking has been omitted for brevity.
424 .Bd -literal -offset indent
425 #include <sys/time.h>
426 #include <stdio.h>
427 #include <stdlib.h>
428 #include <string.h>
429 #include <stdarg.h>
431 #include <sys/socket.h>
432 #include <netinet/in.h>
433 #include <arpa/inet.h>
435 #include "omapip/result.h"
436 #include "dhcpctl.h"
438 int main (int argc, char **argv) {
439 dhcpctl_data_string ipaddrstring = NULL;
440 dhcpctl_data_string value = NULL;
441 dhcpctl_handle connection = NULL;
442 dhcpctl_handle lease = NULL;
443 isc_result_t waitstatus;
444 struct in_addr convaddr;
445 time_t thetime;
447 dhcpctl_initialize ();
449 dhcpctl_connect (&connection, "127.0.0.1",
450 7911, 0);
452 dhcpctl_new_object (&lease, connection,
453 "lease");
455 memset (&ipaddrstring, 0, sizeof
456 ipaddrstring);
458 inet_pton(AF_INET, "10.0.0.101",
459 &convaddr);
461 omapi_data_string_new (&ipaddrstring,
462 4, MDL);
463 memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
465 dhcpctl_set_value (lease, ipaddrstring,
466 "ip-address");
468 dhcpctl_open_object (lease, connection, 0);
470 dhcpctl_wait_for_completion (lease,
471 &waitstatus);
472 if (waitstatus != ISC_R_SUCCESS) {
473 /* server not authoritative */
474 exit (0);
475 }
477 dhcpctl_data_string_dereference(&ipaddrstring,
478 MDL);
480 dhcpctl_get_value (&value, lease, "ends");
482 memcpy(&thetime, value->value, value->len);
484 dhcpctl_data_string_dereference(&value, MDL);
486 fprintf (stdout, "ending time is %s",
487 ctime(&thetime));
488 }
489 .Ed
490 .Sh SEE ALSO
491 omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
492 .Sh AUTHOR
493 .Em dhcpctl
494 is maintained by ISC. To learn more about Internet Systems Consortium,
495 see
496 .B https://www.isc.org