contrib/isc-dhcp/dhcpctl/dhcpctl.3

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