3 .\" Copyright (c) 2000-2001 Internet Software Consortium.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. Neither the name of The Internet Software Consortium nor the names
14 .\" of its contributors may be used to endorse or promote products derived
15 .\" from this software without specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
18 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
19 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 .\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
22 .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
25 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" This software has been written for the Internet Software Consortium
32 .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
33 .\" To learn more about the Internet Software Consortium, see
34 .\" ``http://www.isc.org/''. To learn more about Vixie Enterprises,
35 .\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
36 .\" ``http://www.nominum.com''.
39 OMAPI - Object Management Application Programming Interface
42 OMAPI is an programming layer designed for controlling remote
43 applications, and for querying them for their state. It is currently
44 used by the ISC DHCP server and this outline addresses the parts of
45 OMAPI appropriate to the clients of DHCP server. It does this by also
46 describing the use of a thin API layered on top of OMAPI called
49 OMAPI uses TCP/IP as the transport for server communication, and
50 security can be imposed by having the client and server
51 cryptographically sign messages using a shared secret.
53 dhcpctl works by presenting the client with handles to objects that
54 act as surrogates for the real objects in the server. For example a
55 client will create a handle for a lease object, and will request the
56 server to fill the lease handle's state. The client application can
57 then pull details such as the lease expiration time from the lease
60 Modifications can be made to the server state by creating handles to
61 new objects, or by modifying attributes of handles to existing
62 objects, and then instructing the server to update itself according to
66 The client application must always call dhcpctl_initialize() before
67 making calls to any other dhcpctl functions. This initializes
68 various internal data structures.
70 To create the connection to the server the client must use
71 dhcpctl_connect() function. As well as making the physical connection
72 it will also set up the connection data structures to do
73 authentication on each message, if that is required.
75 All the dhcpctl functions return an integer value of type
76 isc_result_t. A successful call will yield a result of
77 ISC_R_SUCCESS. If the call fails for a reason local to the client
78 (e.g. insufficient local memory, or invalid arguments to the call)
79 then the return value of the dhcpctl function will show that. If the
80 call succeeds but the server couldn't process the request the error
81 value from the server is returned through another way, shown below.
83 The easiest way to understand dhcpctl is to see it in action. The
84 following program is fully functional, but almost all error checking
85 has been removed to make is shorter and easier to understand. This
86 program will query the server running on the localhost for the details
87 of the lease for IP address 10.0.0.101. It will then print out the time
93 #include <sys/socket.h>
95 #include <netinet/in.h>
97 #include <isc/result.h>
98 #include <dhcpctl/dhcpctl.h>
100 int main (int argc, char **argv) {
101 dhcpctl_data_string ipaddrstring = NULL;
102 dhcpctl_data_string value = NULL;
105 All modifications of handles and all accesses of handle data happen
106 via dhcpctl_data_string objects.
109 dhcpctl_handle connection = NULL;
110 dhcpctl_handle lease = NULL;
111 isc_result_t waitstatus;
112 struct in_addr convaddr;
115 dhcpctl_initialize ();
121 dhcpctl_connect (&connection, "127.0.0.1",
125 Sets up the connection to the server. The server normally listens on
126 port 7911 unless configured to do otherwise.
129 dhcpctl_new_object (&lease, connection,
133 Here we create a handle to a lease. This call just sets up local data
134 structure. The server hasn't yet made any association between the
135 client's data structure and any lease it has.
138 memset (&ipaddrstring, 0, sizeof
141 inet_pton(AF_INET, "10.0.0.101",
144 omapi_data_string_new (&ipaddrstring,
148 Create a new data string to storing in the handle.
151 memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
153 dhcpctl_set_value (lease, ipaddrstring,
157 We're setting the ip-address attribute of the lease handle to the
158 given address. We've not set any other attributes so when the server
159 makes the association the ip address will be all it uses to look up
160 the lease in its tables.
163 dhcpctl_open_object (lease, connection, 0);
166 Here we prime the connection with the request to look up the lease in
167 the server and fill up the local handle with the attributes the server
168 will send over in its answer.
171 dhcpctl_wait_for_completion (lease,
175 This call causes the message to get sent to the server (the message to
176 look up the lease and send back the attribute values in the
177 answer). The value in the variable waitstatus when the function
178 returns will be the result from the server. If the message could
179 not be processed properly by the server then the error will be
183 if (waitstatus != ISC_R_SUCCESS) {
184 /* server not authoritative */
188 dhcpctl_data_string_dereference(&ipaddrstring,
192 Clean-up memory we no longer need.
195 dhcpctl_get_value (&value, lease, "ends");
198 Get the attribute named ``ends'' from the lease handle. This is a
199 4-byte integer of the time (in unix epoch seconds) that the lease
204 memcpy(&thetime, value->value, value->len);
205 dhcpctl_data_string_dereference(&value, MDL);
207 fprintf (stdout, "ending time is %s",
213 If the server demands authenticated connections then before opening
214 the connection the user must call dhcpctl_new_authenticator.
217 dhcpctl_handle authenticator = NULL;
218 const char *keyname = "a-key-name";
219 const char *algorithm = "hmac-md5";
220 const char *secret = "a-shared-secret";
222 dhcpctl_new_authenticator (&authenticator,
229 The keyname, algorithm and secret must all match what is specified in
230 the server's dhcpd.conf file:
235 secret "a-shared-secret";
238 # Set the omapi-key value to use
239 # authenticated connections
240 omapi-key "a-key-name";
243 The authenticator handle that is created by the call to
244 dhcpctl_new_authenticator must be given as the last (the 4th) argument
245 to the call to dhcpctl_connect(). All messages will then be signed
246 with the given secret string using the specified algorithm.
248 dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
251 was created by Ted Lemon of Nominum, Inc. Information about Nominum
252 and support contracts for DHCP and BIND can be found at
253 .B http://www.nominum.com. This documentation was written by James
254 Brister of Nominum, Inc.