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