+DHCPCTL(3) DHCP Programmer's Manual DHCPCTL(3)
+
+NAME
+ dhcpctl_initialize - dhcpctl library initialization.
+
+SYNOPSIS
+ #include <dhcpctl/dhcpctl.h>
+
+
+ dhcpctl_status
+ dhcpctl_initialize(void);
+
+ dhcpctl_status
+ dhcpctl_connect(dhcpctl_handle *cxn, const char *host, int port,
+ dhcpctl_handle auth);
+
+ dhcpctl_status
+ dhcpctl_wait_for_completion(dhcpctl_handle object,
+ dhcpctl_status *status);
+
+ dhcpctl_status
+ dhcpctl_get_value(dhcpctl_data_string *value, dhcpctl_handle object,
+ const char *name);
+
+ dhcpctl_status
+ dhcpctl_get_boolean(int *value, dhcpctl_handle object, const char *name);
+
+ dhcpctl_status
+ dhcpctl_set_value(dhcpctl_handle object, dhcpctl_data_string value,
+ const char *name);
+
+ dhcpctl_status
+ dhcpctl_set_string_value(dhcpctl_handle object, const char *value,
+ const char *name);
+
+ dhcpctl_status
+ dhcpctl_set_boolean_value(dhcpctl_handle object, int value,
+ const char *name);
+
+ dhcpctl_status
+ dhcpctl_set_int_value(dhcpctl_handle object, int value,
+ const char *name);
+
+ dhcpctl_status
+ dhcpctl_object_update(dhcpctl_handle connection, dhcpctl_handle object);
+
+ dhcpctl_status
+ dhcpctl_object_refresh(dhcpctl_handle connection, dhcpctl_handle object);
+
+ dhcpctl_status
+ dhcpctl_object_remove(dhcpctl_handle connection, dhcpctl_handle object);
+
+ dhcpctl_status
+ dhcpctl_set_callback(dhcpctl_handle object, void *data,
+ void (*function) (dhcpctl_handle, dhcpctl_status, void *));
+
+ dhcpctl_status
+ dhcpctl_new_authenticator(dhcpctl_handle *object, const char *name,
+ const char *algorithm, const char *secret, unsigned secret_len);
+
+ dhcpctl_status
+ dhcpctl_new_object(dhcpctl_handle *object, dhcpctl_handle connection,
+ const char *object_type);
+
+
+ dhcpctl_status
+ dhcpctl_open_object(dhcpctl_handle object, dhcpctl_handle connection,
+ int flags);
+
+ isc_result_t
+ omapi_data_string_new(dhcpctl_data_string, *data, unsigned, int, length,
+ const, char, *filename,, int, lineno);
+
+ isc_result_t
+ dhcpctl_data_string_dereference(dhcpctl_data_string *, const char *,
+ int);
+
+DESCRIPTION
+ The dhcpctl set of functions provide an API that can be used to communi
+ cate with and manipulate a running ISC DHCP server. All functions return
+ a value of isc_result_t. The return values reflects the result of opera
+ tions to local data structures. If an operation fails on the server for
+ any reason, then the error result will be returned through the second pa
+ rameter of the dhcpctl_wait_for_completion() call.
+
+ dhcpctl_initialize() sets up the data structures the library needs to do
+ its work. This function must be called once before any other.
+
+ 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 as
+ signed to it.
+
+ For example:
+
+ s =3D 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.
+
+ 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 =3D dhcpctl_wait_for_completion(cxn, &wv);
+ if (s !=3D ISC_R_SUCCESS)
+ local_failure(s);
+ else if (wv !=3D ISC_R_SUCCESS)
+ server_failure(wc);
+
+ The call to dhcpctl_wait_for_completion() won't return until the remote
+ message processing completes or the connection to the server is lost.
+
+ 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 dhcpctl_new_object() and opened
+ with 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 =3D NULL;
+ dhcpctl_handle lease;
+ time_t thetime;
+
+ s =3D dhcpctl_get_value (&value, lease, "ends");
+ assert(s =3D=3D ISC_R_SUCCESS && value->len =3D=3D sizeof(thetime));
+ memcpy(&thetime, value->value, value->len);
+
+ dhcpctl_get_boolean() extracts a boolean valued attribute from the object
+ handle.
+
+
+ The dhcpctl_set_value(), dhcpctl_set_string_value(),
+ dhcpctl_set_boolean_value(), and dhcpctl_set_int_value() functions all
+ set a value on the object handle.
+
+ 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 ob
+ ject if permitted.
+
+ 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.
+
+ dhcpctl_object_remove() queues a request for the removal on the server of
+ the object referenced by the handle.
+
+ The 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 giv
+ en by 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 dhcpctl_set_callback().
+
+ The 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
+ dhcpctl_connect().
+
+ 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. "lease". This function only sets up local
+ data structures, it does not queue any messages to be sent to the remote
+ side, dhcpctl_open_object() does that.
+
+ dhcpctl_open_object() builds and queues the request to the remote side.
+ This function is used with handle created via dhcpctl_new_object(). The
+ flags argument is a bit mask with the following values available for set
+ ting:
+
+ 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 al
+ ready set in the handle.
+
+ DHCPCTL_EXCL
+ return and error if the object exists and DHCPCTL_CREATE was al
+ so specified
+
+ The omapi_data_string_new() function allocates a new 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
+
+ dhcpctl_data_string_dereference() deallocates a data string created by
+ omapi_data_string_new(). The memory for the object won't be compelely
+ deallocated until the last reference is released.
+
+EXAMPLES
+
+ The following program will connect to the DHCP server running on the lo
+ cal 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 <stdarg.h>
+ #include <sys/time.h>
+ #include <sys/socket.h>
+ #include <stdio.h>
+ #include <netinet/in.h>
+
+ #include <isc/result.h>
+ #include <dhcpctl/dhcpctl.h>
+
+ int main (int argc, char **argv) {
+ dhcpctl_data_string ipaddrstring =3D NULL;
+ dhcpctl_data_string value =3D NULL;
+ dhcpctl_handle connection =3D NULL;
+ dhcpctl_handle lease =3D 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 !=3D 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));
+ }
+
+SEE ALSO
+ omapi-intro(1)
+
+ DHCP Nov 15, 2000 5
+
+NAME
+ OMAPI - Object Management Application Programming Interface
+
+DESCRIPTION
+
+Overview
+
+ OMAPI is an programming layer designed for controlling remote
+ applications, and for querying them for their state. It is currently
+ used by the ISC DHCP server and this outline addresses the parts of
+ OMAPI appropriate to the clients of DHCP server. It does this by also
+ describing the use of a thin API layered on top of OMAPI called
+ 'dhcpctl'
+
+ OMAPI uses TCP/IP as the transport for server communication, and
+ security can be imposed by having the client and server
+ cryptographically sign messages using a shared secret.
+
+ dhcpctl works by presenting the client with handles to objects that
+ act as surrogates for the real objects in the server. For example a
+ client will create a handle for a lease object, and will request the
+ server to fill the lease handle's state. The client application can
+ then pull details such as the lease expiration time from the lease
+ handle.
+
+ Modifications can be made to the server state by creating handles to
+ new objects, or by modifying attributes of handles to existing
+ objects, and then instructing the server to update itself according to
+ the changes made.
+
+Usage
+
+ The client application must always call dhcpctl_initialize() before
+ making calls to any other dhcpctl functions. This initializes
+ various internal data structures.
+
+ To create the connection to the server the client must use
+ dhcpctl_connect() function. As well as making the physical connection
+ it will also set up the connection data structures to do
+ authentication on each message, if that is required.
+
+ All the dhcpctl functions return an integer value of type
+ isc_result_t. A successful call will yield a result of
+ ISC_R_SUCCESS. If the call fails for a reason local to the client
+ (e.g. insufficient local memory, or invalid arguments to the call)
+ then the return value of the dhcpctl function will show that. If the
+ call succeeds but the server couldn't process the request the error
+ value from the server is returned through another way, shown below.
+
+ The easiest way to understand dhcpctl is to see it in action. The
+ following program is fully functional, but almost all error checking
+ has been removed to make is shorter and easier to understand. This
+ program will query the server running on the localhost for the details
+ of the lease for IP address 10.0.0.101. It will then print out the time
+ the lease ends.
+
+ #include <stdarg.h>
+ #include <sys/time.h>
+ #include <sys/socket.h>
+ #include <stdio.h>
+ #include <netinet/in.h>
+
+ #include <isc/result.h>
+ #include <dhcpctl/dhcpctl.h>
+
+ int main (int argc, char **argv) {
+ dhcpctl_data_string ipaddrstring = NULL;
+ dhcpctl_data_string value = NULL;
+
+ All modifications of handles and all accesses of handle data happen
+ via dhcpctl_data_string objects.
+
+ dhcpctl_handle connection = NULL;
+ dhcpctl_handle lease = NULL;
+ isc_result_t waitstatus;
+ struct in_addr convaddr;
+ time_t thetime;
+
+ dhcpctl_initialize ();
+
+ Required fist step.
+
+ dhcpctl_connect (&connection, "127.0.0.1",
+ 7911, 0);
+
+ Sets up the connection to the server. The server normally listens on
+ port 7911 unless configured to do otherwise.
+
+ dhcpctl_new_object (&lease, connection,
+ "lease");
+
+ Here we create a handle to a lease. This call just sets up local data
+ structure. The server hasn't yet made any association between the
+ client's data structure and any lease it has.
+
+ memset (&ipaddrstring, 0, sizeof
+ ipaddrstring);
+
+ inet_pton(AF_INET, "10.0.0.101",
+ &convaddr);
+
+ omapi_data_string_new (&ipaddrstring,
+ 4, MDL);
+
+ Create a new data string to storing in the handle.
+
+ memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
+
+ dhcpctl_set_value (lease, ipaddrstring,
+ "ip-address");
+
+ We're setting the ip-address attribute of the lease handle to the
+ given address. We've not set any other attributes so when the server
+ makes the association the ip address will be all it uses to look up
+ the lease in its tables.
+
+ dhcpctl_open_object (lease, connection, 0);
+
+ Here we prime the connection with the request to look up the lease in
+ the server and fill up the local handle with the attributes the server
+ will send over in its answer.
+
+ dhcpctl_wait_for_completion (lease,
+ &waitstatus);
+
+ This call causes the message to get sent to the server (the message to
+ look up the lease and send back the attribute values in the
+ answer). The value in the variable waitstatus when the function
+ returns will be the result from the server. If the message could
+ not be processed properly by the server then the error will be
+ reflected here.
+
+ if (waitstatus != ISC_R_SUCCESS) {
+ /* server not authoritative */
+ exit (0);
+ }
+
+ dhcpctl_data_string_dereference(&ipaddrstring,
+ MDL);
+
+ Clean-up memory we no longer need.
+
+ dhcpctl_get_value (&value, lease, "ends");
+
+ Get the attribute named ``ends'' from the lease handle. This is a
+ 4-byte integer of the time (in unix epoch seconds) that the lease
+ will expire.
+
+ memcpy(&thetime, value->value, value->len);
+ dhcpctl_data_string_dereference(&value, MDL);
+
+ fprintf (stdout, "ending time is %s",
+ ctime(&thetime));
+ }
+
+
+Authentication
+
+ If the server demands authenticated connections then before opening
+ the connection the user must call dhcpctl_new_authenticator.
+
+ dhcpctl_handle authenticator = NULL;
+ const char *keyname = "a-key-name";
+ const char *algorithm = "hmac-md5";
+ const char *secret = "a-shared-secret";
+
+ dhcpctl_new_authenticator (&authenticator,
+ keyname,
+ algorithm,
+ secret,
+ strlen(secret) + 1);
+
+ The keyname, algorithm and secret must all match what is specified in
+ the server's dhcpd.conf file:
+
+ key "a-key-name" {
+ algorithm hmac-md5;
+ secret "a-shared-secret";
+ };
+
+ # Set the omapi-key value to use
+ # authenticated connections
+ omapi-key "a-key-name";
+
+ The authenticator handle that is created by the call to
+ dhcpctl_new_authenticator must be given as the last (the 4th) argument
+ to the call to dhcpctl_connect(). All messages will then be signed
+ with the given secret string using the specified algorithm.
+
+SEE ALSO
+
+ dhcpctl(3)
projects / thirdparty / dhcp.git / commitdiff
