Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
omapi(3)		   Library Functions Manual		      omapi(3)

       OMAPI - Object Management Application Programming Interface

       OMAPI  is an programming	layer designed for controlling remote applica-
       tions, and for querying them for	their state. It	is currently  used  by
       the  ISC	 DHCP server and this outline addresses	the parts of OMAPI ap-
       propriate to the	clients	of DHCP	server.	It does	this by	also  describ-
       ing the use of a	thin API layered on top	of OMAPI called	'dhcpctl'

       OMAPI  uses TCP/IP as the transport for server communication, and secu-
       rity 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 de-
       tails 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_con-
       nect() function.	As well	as making the physical connection it will also
       set up the connection data structures to	do authentication on each mes-
       sage, 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 fol-
       lowing 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 prop-
       erly 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_au-
       thenticator must	be given as the	last (the 4th) argument	to the call to
       dhcpctl_connect(). All messages will then be signed with	the given  se-
       cret 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  Con-
       sortium,	see



Want to link to this manual page? Use this URL:

home | help