OMAPI - Object Management Application Programming Interface


   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

   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.


   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 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, "",
                             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,

   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

                  inet_pton(AF_INET, "",

                  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,

   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,

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


   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

                  memcpy(&thetime, value->value, value->len);
                  dhcpctl_data_string_dereference(&value, MDL);

                  fprintf (stdout, "ending time is %s",


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


   dhcpctl(3),   omshell(1),   dhcpd(8),    dhclient(8),    dhcpd.conf(5),


   omapi  is  maintained  by  ISC.   To  learn more about Internet Systems
   Consortium, see


More Linux Commands

nntptest(1) - interactive NNTP test program - Linux man page
nntptest is a utility that allows you to authenticate to a NNTP server and interactively issue commands to it. Once authenticated you may issue any NNTP command

default_store(3) - generic storage of global data. (ManPage)
The purpose of the default storage is three-fold: 1) To create a global storage space without creating a whole bunch of globally accessible variables or a whole

wish(1) - Simple windowing shell (Commands - Linux man page)
Wish is a simple program consisting of the Tcl command language, the Tk toolkit, and a main program that reads commands from standard input or from a file. It c

term_attrs(3ncurses) - curses environment query routines....
The baudrate routine returns the output speed of the terminal. The number returned is in bits per second, for example 9600, and is an integer. The erasechar rou

XF86VidModeSetGammaRamp(3) - Extension library for the XFree
These functions provide an interface to the server extension XFree86-VidModeExtension which allows the video modes to be queried and adjusted dynamically and mo

bzero(3) - write zero-valued bytes - Linux manual page......
The bzero() function sets the first n bytes of the area starting at s to zero (bytes containing \0). RETURN VALUE None. ATTRIBUTES Multithreading (see pthreads(

rstart(1) - a sample implementation of a Remote Start client
Rstart is a simple implementation of a Remote Start client as defined in A Flexible Remote Execution Protocol Based on rsh. It uses rsh as its underlying remote

fonts-conf(5) - Font configuration files - Linux man page...
Fontconfig is a library designed to provide system-wide font configuration, customization and application access. FUNCTIONAL OVERVIEW Fontconfig contains two es

wgetnstr(3ncurses) - accept character strings from curses te
The function getstr is equivalent to a series of calls to getch, until a newline or carriage return is received (the terminating character is not included in th

sighold(3) - System V signal API (Library - Linux man page)
These functions are provided in glibc as a compatibility interface for programs that make use of the historical System V signal API. This API is obsolete: new a

feclearexcept(3) - floating-point rounding and exception han
These eleven functions were defined in C99, and describe the handling of floating-point rounding and exceptions (overflow, zero-divide, etc.). Exceptions The di

XRes(3) - X-Resource extension client library (Man Page)....
X-Resource is an extension that allows a client to query the X server about its usage of various resources. It should not be confused with the X resource databa

We can't live, work or learn in freedom unless the software we use is free.