dhcpctl/dhcpctl.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Project:      DHCP
   4 .\" File:         dhcpctl.3
   5 .\" RCSId:        $Id: dhcpctl.3,v 1.9 2011/04/25 23:43:16 sar Exp $
   6 .\"
   7 .\" Copyright (c) 2011,2014 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 .\"   PO Box 360
  26 .\"   Newmarket, NH 03857 USA
  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 sent to the remote
 301 for processing. The changes made to the attributes 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 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 omitted 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 "omapip/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 is maintained by ISC.  To learn more about Internet Systems Consortium,
 493 see
 494 .B https://www.isc.org