MAN page from Mandrake 9.X dhcp-server-3.0-1.rc12.2mdk.i586.rpm

omapi

Section: C Library Functions (3)
Index

NAME

OMAPI - Object Management Application Programming Interface

DESCRIPTION

OMAPI is an programming layer designed for controlling remoteapplications, and for querying them for their state. It is currentlyused by the ISC DHCP server and this outline addresses the parts ofOMAPI appropriate to the clients of DHCP server. It does this by alsodescribing the use of a thin API layered on top of OMAPI called

OMAPI uses TCP/IP as the transport for server communication, andsecurity can be imposed by having the client and servercryptographically sign messages using a shared secret.

dhcpctl works by presenting the client with handles to objects thatact as surrogates for the real objects in the server. For example aclient will create a handle for a lease object, and will request theserver to fill the lease handle's state. The client application canthen pull details such as the lease expiration time from the leasehandle.

Modifications can be made to the server state by creating handles tonew objects, or by modifying attributes of handles to existingobjects, and then instructing the server to update itself according tothe changes made.

USAGE

The client application must always call dhcpctl_initialize() beforemaking calls to any other dhcpctl functions. This initializes various internal data structures.

To create the connection to the server the client must usedhcpctl_connect() function. As well as making the physical connectionit will also set up the connection data structures to doauthentication on each message, if that is required.

All the dhcpctl functions return an integer value of typeisc_result_t. A successful call will yield a result ofISC_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 thecall succeeds but the server couldn't process the request the errorvalue from the server is returned through another way, shown below.

The easiest way to understand dhcpctl is to see it in action. Thefollowing program is fully functional, but almost all error checkinghas been removed to make is shorter and easier to understand. Thisprogram will query the server running on the localhost for the detailsof the lease for IP address 10.0.0.101. It will then print out the timethe 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 happenvia 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 first step.

                        dhcpctl_connect (&connection, "127.0.0.1",                                         7911, 0);

Sets up the connection to the server. The server normally listens onport 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 datastructure. The server hasn't yet made any association between theclient'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 thegiven address. We've not set any other attributes so when the servermakes the association the ip address will be all it uses to look upthe lease in its tables.

                        dhcpctl_open_object (lease, connection, 0);

Here we prime the connection with the request to look up the lease inthe server and fill up the local handle with the attributes the serverwill send over in its answer.

                        dhcpctl_wait_for_completion (lease,                                                     &waitstatus);

This call causes the message to get sent to the server (the message tolook up the lease and send back the attribute values in theanswer). The value in the variable waitstatus when the functionreturns will be the result from the server. If the message couldnot be processed properly by the server then the error will bereflected 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 a4-byte integer of the time (in unix epoch seconds) that the leasewill 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 openingthe 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 inthe 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 todhcpctl_new_authenticator must be given as the last (the 4th) argumentto the call to dhcpctl_connect(). All messages will then be signedwith the given secret string using the specified algorithm.

AUTHOR

omapiwas created by Ted Lemon of Nominum, Inc. Information about Nominumand support contracts for DHCP and BIND can be found athttp://www.nominum.com. This documentation was written by JamesBrister of Nominum, Inc.

This document was created byman2html,using the manual pages.