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