Provided by: isc-dhcp-dev_4.3.3-5ubuntu12.10_amd64 
NAME
OMAPI - Object Management Application Programming Interface
DESCRIPTION
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 first 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 must all match what is specified in the server's dhcpd.conf
file, excepting that the secret should appear in ´raw´ form, not in base64 as it would in
dhcpd.conf:
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), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
AUTHOR
omapi is maintained by ISC. To learn more about Internet Systems Consortium, see
https://www.isc.org
omapi(3)