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