[#76] Added new functions to man page dhcpctl/dhcpctl.3

[thirdparty/dhcp.git] / dhcpctl / dhcpctl.3

.\" -*- nroff -*-
.\"
.\" Project:      DHCP
.\" File:         dhcpctl.3
.\" RCSId:        $Id: dhcpctl.3,v 1.9 2011/04/25 23:43:16 sar Exp $
.\"
.\" Copyright (c) 2004-2022 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2000-2003 by Internet Software Consortium
.\" Copyright (c) 2000 Nominum, Inc.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"   Internet Systems Consortium, Inc.
.\"   PO Box 360
.\"   Newmarket, NH 03857 USA
.\"   <info@isc.org>
.\"   https://www.isc.org/
.\"
.\" Description:	dhcpctl man page.
.\"
.\"
.Dd Nov 15, 2000
.Dt DHCPCTL 3
.Os DHCP 3
.ds vT DHCP Programmer's Manual
.\"
.\"
.\"
.Sh NAME
.Nm dhcpctl_initialize
.Nd dhcpctl library initialization.
.\"
.\"
.\"
.Sh SYNOPSIS
.Fd #include <dhcpctl/dhcpctl.h>
.Ft dhcpctl_status
.Fo dhcpctl_initialize
.Fa void
.Fc
.\"
.Ft dhcpctl_status
.Fo dhcpctl_connect
.Fa "dhcpctl_handle *cxn"
.Fa "const char *host"
.Fa "int port"
.Fa "dhcpctl_handle auth"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_disconnect
.Fa "dhcpctl_handle *cxn"
.Fa "int force"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_wait_for_completion
.Fa "dhcpctl_handle object"
.Fa "dhcpctl_status *status"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_timed_wait_for_completion
.Fa "dhcpctl_handle object"
.Fa "struct timeval *timeout"
.Fa "dhcpctl_status *status"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_get_value
.Fa "dhcpctl_data_string *value"
.Fa "dhcpctl_handle object"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_get_boolean
.Fa "int *value"
.Fa "dhcpctl_handle object"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_value
.Fa "dhcpctl_handle object"
.Fa "dhcpctl_data_string value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_string_value
.Fa "dhcpctl_handle object"
.Fa "const char *value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_boolean_value
.Fa "dhcpctl_handle object"
.Fa "int value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_int_value
.Fa "dhcpctl_handle object"
.Fa "int value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_object_update
.Fa "dhcpctl_handle connection"
.Fa "dhcpctl_handle object"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_object_refresh
.Fa "dhcpctl_handle connection"
.Fa "dhcpctl_handle object"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_object_remove
.Fa "dhcpctl_handle connection"
.Fa "dhcpctl_handle object"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_callback
.Fa "dhcpctl_handle object"
.Fa "void *data"
.Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_new_authenticator
.Fa "dhcpctl_handle *object"
.Fa "const char *name"
.Fa "const char *algorithm"
.Fa "const char *secret"
.Fa "unsigned secret_len"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_new_object
.Fa "dhcpctl_handle *object"
.Fa "dhcpctl_handle connection"
.Fa "const char *object_type"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_open_object
.Fa "dhcpctl_handle object"
.Fa "dhcpctl_handle connection"
.Fa "int flags"
.Fc
.\"
.\"
.\"
.Ft isc_result_t
.Fo omapi_data_string_new
.Fa dhcpctl_data_string *data
.Fa unsigned int length
.Fa const char *filename,
.Fa int lineno
.Fc
.\"
.\"
.\"
.Ft isc_result_t
.Fo dhcpctl_data_string_dereference
.Fa "dhcpctl_data_string *"
.Fa "const char *"
.Fa "int"
.Fc
.Sh DESCRIPTION
The dhcpctl set of functions provide an API that can be used to communicate
with and manipulate a running ISC DHCP server. All functions return a value of
.Dv isc_result_t .
The return values reflects the result of operations to local data
structures. If an operation fails on the server for any reason, then the error
result will be returned through the
second parameter of the
.Fn dhcpctl_wait_for_completion
call.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_initialize
sets up the data structures the library needs to do its work. This function
must be called once before any other.
.Pp
.Fn dhcpctl_connect
opens a connection to the DHCP server at the given host and port. If an
authenticator has been created for the connection, then it is given as the 4th
argument. On a successful return the address pointed at by the first
argument will have a new connection object assigned to it.
.Pp
For example:
.Bd -literal -offset indent
s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
.Ed
.Pp
connects to the DHCP server on the localhost via port 7911 (the standard
OMAPI port). No authentication is used for the connection.
.\"
.\"
.\"
.Pp

.Fn dhcpctl_disconnect
closes the open connection specified by the first parameter, \fBcxn\fR.  Note
that this call will free the connection object and \fBcxn\fR will be set to
 nul.  If the second parameter,\fBforce\fR, is nonzero, the connection will be
closed immediately. Otherwise the receiving end will be shut down but any
unsent data will be sent before actually closing the socket.  Note that
disconnecting only destroys the connection object, any other objects previously
created will still exist.
.Pp
For example:
.Bd -literal -offset indent
s = dhcpctl_disconnect(&cxn, 1);
.Ed
.Pp
will close the connection immediately.  This funcion should be considered
\fBEXPERIMENTAL\fR.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_wait_for_completion
flushes a pending message to the server and waits for the response. The result
of the request as processed on the server is returned via the second
parameter.
.Bd -literal -offset indent
s = dhcpctl_wait_for_completion(cxn, &wv);
if (s != ISC_R_SUCCESS)
	local_failure(s);
else if (wv != ISC_R_SUCCESS)
	server_failure(wc);
.Ed
.Pp
The call to
.Fn dhcpctl_wait_for_completion
won't return until the remote message processing completes or the connection
to the server is lost.
.\"
.\"
.\"
.Pp

.Fn dhcpctl_timed_wait_for_completion
flushes a pending message to the server and waits for the response.  How long
the function waits for a response is dictated by the value of the second
parameter, \fBtimeout\fR. If the value is null, it will wait indefinetly or
until the connection is lost. Otherwise it will wait for the amount of time
specified by \fBtimeout\fR (tv_sec:tv_usec). Values of zero for both fields
are valid but not recommended.  The result of the request as processed on the
server is returned via the third parameter.  An example is shown below:
.Bd -literal -offset indent

struct timeval timeout;
timeout.tv_sec = 5;   /* wait for 5 seconds */
timeout.tv_usec = 0;

s = dhcpctl_wait_for_completion(cxn, &timeout, &wv);
if (s != ISC_R_SUCCESS) {
	local_failure(s);
} else if (wv != ISC_R_SUCCESS) {
	server_failure(wc);
}
.Ed
.Pp
If the function times out, the status returned will be ISC_R_TIMEDOUT. Please
note that even though the function is no longer waiting for a response, the
server does not abandon the request and may still respond by writing the
response to the socket. A subsequent call to either this function or
\fBdhcpctl_wait_for_completion()\fR will see that data and read it. Depending
on the application logic flow this may or may not be desired.  Currently though
only mechanism for "flushing" this data is to close the connection by calling
\fBdisconnet()\fR, and then reconnecting via \fBconnect()\fR.  Please note
this function should be considered \fBEXPERIMENTAL\fR.

.\"
.\"
.\"
.Pp
.Fn dhcpctl_get_value
extracts a value of an attribute from the handle. The value can be of any
length and is treated as a sequence of bytes.  The handle must have been
created first with
.Fn dhcpctl_new_object
and opened with
.Fn dhcpctl_open_object .
The value is returned via the parameter named
.Dq value .
The last parameter is the name of attribute to retrieve.
.Bd -literal -offset indent
dhcpctl_data_string value = NULL;
dhcpctl_handle lease;
time_t thetime;

s = dhcpctl_get_value (&value, lease, "ends");
assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
memcpy(&thetime, value->value, value->len);
.Ed
.\"
.\"
.\"
.Pp
.Fn dhcpctl_get_boolean
extracts a boolean valued attribute from the object handle.
.\"
.\"
.\"
.Pp
The
.Fn dhcpctl_set_value ,
.Fn dhcpctl_set_string_value ,
.Fn dhcpctl_set_boolean_value ,
and
.Fn dhcpctl_set_int_value
functions all set a value on the object handle.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_object_update
function queues a request for
all the changes made to the object handle be sent to the remote
for processing. The changes made to the attributes on the handle will be
applied to remote object if permitted.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_object_refresh
queues up a request for a fresh copy of all the attribute values to be sent
from the remote to
refresh the values in the local object handle.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_object_remove
queues a request for the removal on the server of the object referenced by the
handle.
.\"
.\"
.\"
.Pp
The
.Fn dhcpctl_set_callback
function sets up a user-defined function to be called when an event completes
on the given object handle. This is needed for asynchronous handling of
events, versus the synchronous handling given by
.Fn dhcpctl_wait_for_completion .
When the function is called the first parameter is the object the event
arrived for, the second is the status of the message that was processed, the
third is the same value as the second parameter given to
.Fn dhcpctl_set_callback .
.\"
.\"
.\"
.Pp
The
.Fn dhcpctl_new_authenticator
creates a new authenticator object to be used for signing the messages
that cross over the network. The
.Dq name ,
.Dq algorithm ,
and
.Dq secret
values must all match what the server uses and are defined in its
configuration file. The created object is returned through the first parameter
and must be used as the 4th parameter to
.Fn dhcpctl_connect .
Note that the 'secret' value must not be base64 encoded, which is different
from how the value appears in the dhcpd.conf file.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_new_object
creates a local handle for an object on the server. The
.Dq object_type
parameter is the ascii name of the type of object being accessed. e.g.
.Qq lease .
This function only sets up local data structures, it does not queue any
messages
to be sent to the remote side,
.Fn dhcpctl_open_object
does that.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_open_object
builds and queues the request to the remote side. This function is used with
handle created via
.Fn dhcpctl_new_object .
The flags argument is a bit mask with the following values available for
setting:
.Bl -tag -offset indent -width 20
.It DHCPCTL_CREATE
if the object does not exist then the remote will create it
.It DHCPCTL_UPDATE
update the object on the remote side using the
attributes already set in the handle.
.It DHCPCTL_EXCL
return and error if the object exists and DHCPCTL_CREATE
was also specified
.El
.\"
.\"
.\"
.Pp
The
.Fn omapi_data_string_new
function allocates a new
.Ft dhcpctl_data_string
object. The data string will be large enough to hold
.Dq length
bytes of data. The
.Dq file
and
.Dq lineno
arguments are the source file location the call is made from, typically by
using the
.Dv __FILE__
and
.Dv __LINE__
macros or the
.Dv MDL
macro defined in
.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_data_string_dereference
deallocates a data string created by
.Fn omapi_data_string_new .
The memory for the object won't be freed until the last reference is
released.
.Sh EXAMPLES
.Pp
The following program will connect to the DHCP server running on the local
host and will get the details of the existing lease for IP address
10.0.0.101. It will then print out the time the lease is due to expire. Note
that most error checking has been omitted for brevity.
.Bd -literal -offset indent
#include <sys/time.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdarg.h>

#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>

#include "omapip/result.h"
#include "dhcpctl.h"

int main (int argc, char **argv) {
	dhcpctl_data_string ipaddrstring = NULL;
	dhcpctl_data_string value = NULL;
	dhcpctl_handle connection = NULL;
	dhcpctl_handle lease = NULL;
	isc_result_t waitstatus;
	struct in_addr convaddr;
	time_t thetime;

        dhcpctl_initialize ();

        dhcpctl_connect (&connection, "127.0.0.1",
			 7911, 0);

        dhcpctl_new_object (&lease, connection,
			    "lease");

        memset (&ipaddrstring, 0, sizeof
		ipaddrstring);

        inet_pton(AF_INET, "10.0.0.101",
		  &convaddr);

	omapi_data_string_new (&ipaddrstring,
			       4, MDL);
	memcpy(ipaddrstring->value, &convaddr.s_addr, 4);

	dhcpctl_set_value (lease, ipaddrstring,
			   "ip-address");

	dhcpctl_open_object (lease, connection, 0);

	dhcpctl_wait_for_completion (lease,
				     &waitstatus);
        if (waitstatus != ISC_R_SUCCESS) {
		/* server not authoritative */
		exit (0);
        }

	dhcpctl_data_string_dereference(&ipaddrstring,
					MDL);

        dhcpctl_get_value (&value, lease, "ends");

	memcpy(&thetime, value->value, value->len);

	dhcpctl_data_string_dereference(&value, MDL);

	fprintf (stdout, "ending time is %s",
		 ctime(&thetime));
}
.Ed
.Sh SEE ALSO
omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
.Sh AUTHOR
.Em dhcpctl
is maintained by ISC.  To learn more about Internet Systems Consortium,
see
.B https://www.isc.org