dhcpctl (3)

NAME
SYNOPSIS
DESCRIPTION
EXAMPLES
SEE ALSO
AUTHOR

NAME

dhcpctl_initialize - dhcpctl library initialization.

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

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 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.

Fn dhcpctl_initialize sets up the data structures the library needs to do its work. This function must be called once before any other.

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.

For example:

s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);

connects to the DHCP server on the localhost via port 7911 (the standard OMAPI port). No authentication is used for the connection.

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.

s = dhcpctl_wait_for_completion(cxn, &wv);
if (s != ISC_R_SUCCESS) 
        local_failure(s);
else if (wv != ISC_R_SUCCESS)
        server_failure(wc);

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.

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 ``value'' The last parameter is the name of attribute to retrieve.

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);

Fn dhcpctl_get_boolean extracts a boolean valued attribute from the object handle.

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.

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.

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.

Fn dhcpctl_object_remove queues a request for the removal on the server of the object referenced by the handle.

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 .

The Fn dhcpctl_new_authenticator creates a new authenticator object to be used for signing the messages that cross over the network. The ``name'' ``algorithm'' and ``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.

Fn dhcpctl_new_object creates a local handle for an object on the the server. The ``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.

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:

DHCPCTL_CREATE: if the object does not exist then the remote will create it
DHCPCTL_UPDATE: update the object on the remote side using the attributes already set in the handle.
DHCPCTL_EXCL: return and error if the object exists and DHCPCTL_CREATE was also specified

The Fn omapi_data_string_new function allocates a new Ft dhcpctl_data_string object. The data string will be large enough to hold ``length'' bytes of data. The ``file '' and ``lineno'' arguments are the source file location the call is made from, typically by using the __FILE__ and __LINE__ macros or the MDL macro defined in

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.

EXAMPLES

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.

#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));
}

AUTHOR

dhcpctl was written by Ted Lemon of Nominum, Inc. This preliminary documentation was written by James Brister of Nominum, Inc.