1omapi(3) Library Functions Manual omapi(3)
2
6 OMAPI - Object Management Application Programming Interface
7
9 OMAPI is an programming layer designed for controlling remote applica‐
10 tions, and for querying them for their state. It is currently used by
11 the ISC DHCP server and this outline addresses the parts of OMAPI
12 appropriate to the clients of DHCP server. It does this by also
13 describing the use of a thin API layered on top of OMAPI called
14 OMAPI uses TCP/IP as the transport for server communication, and secu‐
16 rity can be imposed by having the client and server cryptographically
17 sign messages using a shared secret.
18 dhcpctl works by presenting the client with handles to objects that act
20 as surrogates for the real objects in the server. For example a client
21 will create a handle for a lease object, and will request the server to
22 fill the lease handle's state. The client application can then pull
23 details such as the lease expiration time from the lease handle.
24 Modifications can be made to the server state by creating handles to
26 new objects, or by modifying attributes of handles to existing objects,
27 and then instructing the server to update itself according to the
28 changes made.
29
31 The client application must always call dhcpctl_initialize() before
32 making calls to any other dhcpctl functions. This initializes various
33 internal data structures.
34 To create the connection to the server the client must use dhcpctl_con‐
36 nect() function. As well as making the physical connection it will also
37 set up the connection data structures to do authentication on each mes‐
38 sage, if that is required.
39 All the dhcpctl functions return an integer value of type isc_result_t.
41 A successful call will yield a result of ISC_R_SUCCESS. If the call
42 fails for a reason local to the client (e.g. insufficient local memory,
43 or invalid arguments to the call) then the return value of the dhcpctl
44 function will show that. If the call succeeds but the server couldn't
45 process the request the error value from the server is returned through
46 another way, shown below.
47 The easiest way to understand dhcpctl is to see it in action. The fol‐
49 lowing program is fully functional, but almost all error checking has
50 been removed to make is shorter and easier to understand. This program
51 will query the server running on the localhost for the details of the
52 lease for IP address 10.0.0.101. It will then print out the time the
53 lease ends.
54 #include <stdarg.h>
56 #include <sys/time.h>
57 #include <sys/socket.h>
58 #include <stdio.h>
59 #include <netinet/in.h>
60 #include <isc/result.h>
62 #include <dhcpctl/dhcpctl.h>
63 int main (int argc, char **argv) {
65 dhcpctl_data_string ipaddrstring = NULL;
66 dhcpctl_data_string value = NULL;
67 All modifications of handles and all accesses of handle data happen via
69 dhcpctl_data_string objects.
70 dhcpctl_handle connection = NULL;
72 dhcpctl_handle lease = NULL;
73 isc_result_t waitstatus;
74 struct in_addr convaddr;
75 time_t thetime;
76 dhcpctl_initialize ();
78 Required first step.
80 dhcpctl_connect (&connection, "127.0.0.1",
82 7911, 0);
83 Sets up the connection to the server. The server normally listens on
85 port 7911 unless configured to do otherwise.
86 dhcpctl_new_object (&lease, connection,
88 "lease");
89 Here we create a handle to a lease. This call just sets up local data
91 structure. The server hasn't yet made any association between the
92 client's data structure and any lease it has.
93 memset (&ipaddrstring, 0, sizeof
95 ipaddrstring);
96 inet_pton(AF_INET, "10.0.0.101",
98 &convaddr);
99 omapi_data_string_new (&ipaddrstring,
101 4, MDL);
102 Create a new data string to storing in the handle.
104 memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
106 dhcpctl_set_value (lease, ipaddrstring,
108 "ip-address");
109 We're setting the ip-address attribute of the lease handle to the given
111 address. We've not set any other attributes so when the server makes
112 the association the ip address will be all it uses to look up the lease
113 in its tables.
114 dhcpctl_open_object (lease, connection, 0);
116 Here we prime the connection with the request to look up the lease in
118 the server and fill up the local handle with the attributes the server
119 will send over in its answer.
120 dhcpctl_wait_for_completion (lease,
122 &waitstatus);
123 This call causes the message to get sent to the server (the message to
125 look up the lease and send back the attribute values in the answer).
126 The value in the variable waitstatus when the function returns will be
127 the result from the server. If the message could not be processed prop‐
128 erly by the server then the error will be reflected here.
129 if (waitstatus != ISC_R_SUCCESS) {
131 /* server not authoritative */
132 exit (0);
133 }
134 dhcpctl_data_string_dereference(&ipaddrstring,
136 MDL);
137 Clean-up memory we no longer need.
139 dhcpctl_get_value (&value, lease, "ends");
141 Get the attribute named ``ends'' from the lease handle. This is a
143 4-byte integer of the time (in unix epoch seconds) that the lease will
144 expire.
145 memcpy(&thetime, value->value, value->len);
148 dhcpctl_data_string_dereference(&value, MDL);
149 fprintf (stdout, "ending time is %s",
151 ctime(&thetime));
152 }
153
156 If the server demands authenticated connections then before opening the
157 connection the user must call dhcpctl_new_authenticator.
158 dhcpctl_handle authenticator = NULL;
160 const char *keyname = "a-key-name";
161 const char *algorithm = "hmac-md5";
162 const char *secret = "a-shared-secret";
163 dhcpctl_new_authenticator (&authenticator,
165 keyname,
166 algorithm,
167 secret,
168 strlen(secret) + 1);
169 The keyname, algorithm and must all match what is specified in the
171 server's dhcpd.conf file, excepting that the secret should appear in
172 'raw' form, not in base64 as it would in dhcpd.conf:
173 key "a-key-name" {
175 algorithm hmac-md5;
176 secret "a-shared-secret";
177 };
178 # Set the omapi-key value to use
180 # authenticated connections
181 omapi-key a-key-name;
182 The authenticator handle that is created by the call to
184 dhcpctl_new_authenticator must be given as the last (the 4th) argument
185 to the call to dhcpctl_connect(). All messages will then be signed with
186 the given secret string using the specified algorithm.
187
189 dhcpctl(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5),
190 dhclient.conf(5).
191
193 omapi was created by Ted Lemon of Nominum, Inc. Information about
194 Nominum and support contracts for DHCP and BIND can be found at
195 http://www.nominum.com. This documentation was written by James Brister
196 of Nominum, Inc.
197 omapi(3)