827332
.\" -*- nroff -*-
827332
.\"
827332
.\" Project:      DHCP
827332
.\" File:         dhcpctl.3
827332
.\" RCSId:        $Id$
827332
.\" 
827332
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
827332
.\" Copyright (c) 2000-2003 by Internet Software Consortium
827332
.\" Copyright (c) 2000 Nominum, Inc.
827332
.\"
827332
.\" Permission to use, copy, modify, and distribute this software for any
827332
.\" purpose with or without fee is hereby granted, provided that the above
827332
.\" copyright notice and this permission notice appear in all copies.
827332
.\"
827332
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
827332
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
827332
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
827332
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
827332
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
827332
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
827332
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
827332
.\"
827332
.\"   Internet Systems Consortium, Inc.
827332
.\"   950 Charter Street
827332
.\"   Redwood City, CA 94063
827332
.\"   <info@isc.org>
827332
.\"   http://www.isc.org/
827332
.\"     
827332
.\" Description:	dhcpctl man page.
827332
.\" 
827332
.\"
827332
.Dd Nov 15, 2000
827332
.Dt DHCPCTL 3
827332
.Os DHCP 3
827332
.ds vT DHCP Programmer's Manual
827332
.\"
827332
.\"
827332
.\"
827332
.Sh NAME
827332
.Nm dhcpctl_initialize
827332
.Nd dhcpctl library initialization.
827332
.\"
827332
.\"
827332
.\"
827332
.Sh SYNOPSIS
827332
.Fd #include <dhcpctl.h>
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_initialize
827332
.Fa void
827332
.Fc
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_connect
827332
.Fa "dhcpctl_handle *cxn"
827332
.Fa "const char *host"
827332
.Fa "int port"
827332
.Fa "dhcpctl_handle auth"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_wait_for_completion
827332
.Fa "dhcpctl_handle object"
827332
.Fa "dhcpctl_status *status"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_get_value
827332
.Fa "dhcpctl_data_string *value"
827332
.Fa "dhcpctl_handle object"
827332
.Fa "const char *name"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_get_boolean
827332
.Fa "int *value"
827332
.Fa "dhcpctl_handle object"
827332
.Fa "const char *name"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_set_value
827332
.Fa "dhcpctl_handle object"
827332
.Fa "dhcpctl_data_string value"
827332
.Fa "const char *name"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_set_string_value
827332
.Fa "dhcpctl_handle object"
827332
.Fa "const char *value"
827332
.Fa "const char *name"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_set_boolean_value
827332
.Fa "dhcpctl_handle object"
827332
.Fa "int value"
827332
.Fa "const char *name"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_set_int_value
827332
.Fa "dhcpctl_handle object"
827332
.Fa "int value"
827332
.Fa "const char *name"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_object_update
827332
.Fa "dhcpctl_handle connection"
827332
.Fa "dhcpctl_handle object"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_object_refresh
827332
.Fa "dhcpctl_handle connection"
827332
.Fa "dhcpctl_handle object"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_object_remove
827332
.Fa "dhcpctl_handle connection"
827332
.Fa "dhcpctl_handle object"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_set_callback
827332
.Fa "dhcpctl_handle object"
827332
.Fa "void *data"
827332
.Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_new_authenticator
827332
.Fa "dhcpctl_handle *object"
827332
.Fa "const char *name"
827332
.Fa "const char *algorithm"
827332
.Fa "const char *secret"
827332
.Fa "unsigned secret_len"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_new_object
827332
.Fa "dhcpctl_handle *object"
827332
.Fa "dhcpctl_handle connection"
827332
.Fa "const char *object_type"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft dhcpctl_status
827332
.Fo dhcpctl_open_object
827332
.Fa "dhcpctl_handle object"
827332
.Fa "dhcpctl_handle connection"
827332
.Fa "int flags"
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft isc_result_t
827332
.Fo omapi_data_string_new
827332
.Fa dhcpctl_data_string *data
827332
.Fa unsigned int length
827332
.Fa const char *filename,
827332
.Fa int lineno
827332
.Fc
827332
.\"
827332
.\"
827332
.\"
827332
.Ft isc_result_t
827332
.Fo dhcpctl_data_string_dereference
827332
.Fa "dhcpctl_data_string *"
827332
.Fa "const char *"
827332
.Fa "int"
827332
.Fc
827332
.Sh DESCRIPTION
827332
The dhcpctl set of functions provide an API that can be used to communicate
827332
with and manipulate a running ISC DHCP server. All functions return a value of
827332
.Dv isc_result_t .
827332
The return values reflects the result of operations to local data
827332
structures. If an operation fails on the server for any reason, then the error
827332
result will be returned through the
827332
second parameter of the 
827332
.Fn dhcpctl_wait_for_completion 
827332
call.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_initialize
827332
sets up the data structures the library needs to do its work. This function
827332
must be called once before any other.
827332
.Pp
827332
.Fn dhcpctl_connect
827332
opens a connection to the DHCP server at the given host and port. If an
827332
authenticator has been created for the connection, then it is given as the 4th
827332
argument. On a successful return the address pointed at by the first
827332
argument will have a new connection object assigned to it.
827332
.Pp
827332
For example:
827332
.Bd -literal -offset indent
827332
s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
827332
.Ed
827332
.Pp
827332
connects to the DHCP server on the localhost via port 7911 (the standard
827332
OMAPI port). No authentication is used for the connection.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_wait_for_completion
827332
flushes a pending message to the server and waits for the response. The result
827332
of the request as processed on the server is returned via the second
827332
parameter.
827332
.Bd -literal -offset indent
827332
s = dhcpctl_wait_for_completion(cxn, &wv);
827332
if (s != ISC_R_SUCCESS) 
827332
	local_failure(s);
827332
else if (wv != ISC_R_SUCCESS)
827332
	server_failure(wc);
827332
.Ed
827332
.Pp
827332
The call to 
827332
.Fn dhcpctl_wait_for_completion
827332
won't return until the remote message processing completes or the connection
827332
to the server is lost.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_get_value
827332
extracts a value of an attribute from the handle. The value can be of any
827332
length and is treated as a sequence of bytes.  The handle must have been
827332
created first with
827332
.Fn dhcpctl_new_object
827332
and opened with
827332
.Fn dhcpctl_open_object .
827332
The value is returned via the parameter named
827332
.Dq value .
827332
The last parameter is the name of attribute to retrieve.
827332
.Bd -literal -offset indent
827332
dhcpctl_data_string value = NULL;
827332
dhcpctl_handle lease;
827332
time_t thetime;
827332
827332
s = dhcpctl_get_value (&value, lease, "ends");
827332
assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
827332
memcpy(&thetime, value->value, value->len);
827332
.Ed
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_get_boolean
827332
extracts a boolean valued attribute from the object handle.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
The
827332
.Fn dhcpctl_set_value ,
827332
.Fn dhcpctl_set_string_value ,
827332
.Fn dhcpctl_set_boolean_value ,
827332
and
827332
.Fn dhcpctl_set_int_value
827332
functions all set a value on the object handle. 
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_object_update
827332
function queues a request for
827332
all the changes made to the object handle be be sent to the remote
827332
for processing. The changes made to the atributes on the handle will be
827332
applied to remote object if permitted.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_object_refresh
827332
queues up a request for a fresh copy of all the attribute values to be sent
827332
from the remote to
827332
refresh the values in the local object handle.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_object_remove
827332
queues a request for the removal on the server of the object referenced by the
827332
handle.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
The 
827332
.Fn dhcpctl_set_callback
827332
function sets up a user-defined function to be called when an event completes
827332
on the given object handle. This is needed for asynchronous handling of
827332
events, versus the synchronous handling given by
827332
.Fn dhcpctl_wait_for_completion .
827332
When the function is called the first parameter is the object the event
827332
arrived for, the second is the status of the message that was processed, the
827332
third is the same value as the second parameter given to 
827332
.Fn dhcpctl_set_callback .
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
The 
827332
.Fn dhcpctl_new_authenticator
827332
creates a new authenticator object to be used for signing the messages
827332
that cross over the network. The 
827332
.Dq name ,
827332
.Dq algorithm ,
827332
and 
827332
.Dq secret
827332
values must all match what the server uses and are defined in its
827332
configuration file. The created object is returned through the first parameter
827332
and must be used as the 4th parameter to 
827332
.Fn dhcpctl_connect .
827332
Note that the 'secret' value must not be base64 encoded, which is different
827332
from how the value appears in the dhcpd.conf file.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_new_object
827332
creates a local handle for an object on the the server. The 
827332
.Dq object_type
827332
parameter is the ascii name of the type of object being accessed. e.g. 
827332
.Qq lease .
827332
This function only sets up local data structures, it does not queue any 
827332
messages
827332
to be sent to the remote side,
827332
.Fn dhcpctl_open_object
827332
does that.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_open_object
827332
builds and queues the request to the remote side. This function is used with
827332
handle created via
827332
.Fn dhcpctl_new_object .
827332
The flags argument is a bit mask with the following values available for
827332
setting:
827332
.Bl -tag -offset indent -width 20
827332
.It DHCPCTL_CREATE
827332
if the object does not exist then the remote will create it
827332
.It DHCPCTL_UPDATE
827332
update the object on the remote side using the
827332
attributes already set in the handle.
827332
.It DHCPCTL_EXCL
827332
return and error if the object exists and DHCPCTL_CREATE
827332
was also specified
827332
.El
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
The 
827332
.Fn omapi_data_string_new
827332
function allocates a new
827332
.Ft dhcpctl_data_string
827332
object. The data string will be large enough to hold 
827332
.Dq length
827332
bytes of data. The
827332
.Dq file 
827332
and
827332
.Dq lineno
827332
arguments are the source file location the call is made from, typically by
827332
using the 
827332
.Dv __FILE__
827332
and
827332
.Dv __LINE__
827332
macros or the 
827332
.Dv MDL
827332
macro defined in
827332
.
827332
.\"
827332
.\"
827332
.\"
827332
.Pp
827332
.Fn dhcpctl_data_string_dereference
827332
deallocates a data string created by
827332
.Fn omapi_data_string_new .
827332
The memory for the object won't be freed until the last reference is
827332
released.
827332
.Sh EXAMPLES
827332
.Pp 
827332
The following program will connect to the DHCP server running on the local
827332
host and will get the details of the existing lease for IP address
827332
10.0.0.101. It will then print out the time the lease is due to expire. Note
827332
that most error checking has been ommitted for brevity.
827332
.Bd -literal -offset indent
827332
#include <stdarg.h>
827332
#include <sys time.h="">
827332
#include <sys socket.h="">
827332
#include <stdio.h>
827332
#include <netinet in.h="">
827332
827332
#include <isc result.h="">
827332
#include <dhcpctl.h>
827332
827332
int main (int argc, char **argv) {
827332
	dhcpctl_data_string ipaddrstring = NULL;
827332
	dhcpctl_data_string value = NULL;
827332
	dhcpctl_handle connection = NULL;
827332
	dhcpctl_handle lease = NULL;
827332
	isc_result_t waitstatus;
827332
	struct in_addr convaddr;
827332
	time_t thetime;
827332
827332
        dhcpctl_initialize ();
827332
827332
        dhcpctl_connect (&connection, "127.0.0.1",
827332
			 7911, 0);
827332
	
827332
        dhcpctl_new_object (&lease, connection,
827332
			    "lease");
827332
827332
        memset (&ipaddrstring, 0, sizeof
827332
		ipaddrstring);
827332
827332
        inet_pton(AF_INET, "10.0.0.101",
827332
		  &convaddr);
827332
827332
	omapi_data_string_new (&ipaddrstring,
827332
			       4, MDL);
827332
	memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
827332
827332
	dhcpctl_set_value (lease, ipaddrstring,
827332
			   "ip-address");
827332
827332
	dhcpctl_open_object (lease, connection, 0);
827332
827332
	dhcpctl_wait_for_completion (lease,
827332
				     &waitstatus);
827332
        if (waitstatus != ISC_R_SUCCESS) {
827332
		/* server not authoritative */
827332
		exit (0);
827332
        }
827332
827332
	dhcpctl_data_string_dereference(&ipaddrstring,
827332
					MDL);
827332
827332
        dhcpctl_get_value (&value, lease, "ends");
827332
827332
	memcpy(&thetime, value->value, value->len);
827332
827332
	dhcpctl_data_string_dereference(&value, MDL);
827332
827332
	fprintf (stdout, "ending time is %s",
827332
		 ctime(&thetime));
827332
}
827332
.Ed
827332
.Sh SEE ALSO
827332
omapi(3), omshell(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
827332
.Sh AUTHOR
827332
.Em dhcpctl
827332
was written by Ted Lemon of Nominum, Inc.
827332
This preliminary documentation was written by James Brister of Nominum, Inc.