diff options
Diffstat (limited to 'dhcpctl/dhcpctl.3')
| -rw-r--r-- | dhcpctl/dhcpctl.3 | 493 |
1 files changed, 493 insertions, 0 deletions
diff --git a/dhcpctl/dhcpctl.3 b/dhcpctl/dhcpctl.3 new file mode 100644 index 0000000..9aa1851 --- /dev/null +++ b/dhcpctl/dhcpctl.3 @@ -0,0 +1,493 @@ +.\" -*- nroff -*- +.\" +.\" Project: DHCP +.\" File: dhcpctl.3 +.\" RCSId: $Id: dhcpctl.3,v 1.7.24.2 2011-04-25 23:49:52 sar Exp $ +.\" +.\" Copyright (c) 2011 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 2004,2009 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> +.\" 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_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 <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 +was written by Ted Lemon of Nominum, Inc. +This preliminary documentation was written by James Brister of Nominum, Inc. |