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.