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