489 lines
11 KiB
Groff
489 lines
11 KiB
Groff
.\" -*- nroff -*-
|
|
.\"
|
|
.\" Project: DHCP
|
|
.\" File: dhcpctl.3
|
|
.\" RCSId: $Id: dhcpctl.3,v 1.1 2007/11/12 23:16:08 dcantrel Exp $
|
|
.\"
|
|
.\" Copyright (c) 2004 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.
|
|
.\" 950 Charter Street
|
|
.\" Redwood City, CA 94063
|
|
.\" <info@isc.org>
|
|
.\" http://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.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_wait_for_completion
|
|
.Fa "dhcpctl_handle object"
|
|
.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_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_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 be sent to the remote
|
|
for processing. The changes made to the atributes 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 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 ommitted for brevity.
|
|
.Bd -literal -offset indent
|
|
#include <stdarg.h>
|
|
#include <sys/time.h>
|
|
#include <sys/socket.h>
|
|
#include <stdio.h>
|
|
#include <netinet/in.h>
|
|
|
|
#include <isc/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(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
|
|
.Sh AUTHOR
|
|
.Em dhcpctl
|
|
was written by Ted Lemon of Nominum, Inc.
|
|
This preliminary documentation was written by James Brister of Nominum, Inc.
|