Merge from vendor branch DHCP:
[dragonfly.git] / contrib / dhcp-3.0 / omapip / omapi.3
1 .\"     omapi.3
2 .\"
3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 2000-2003 by Internet Software Consortium
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .\"   Internet Systems Consortium, Inc.
19 .\"   950 Charter Street
20 .\"   Redwood City, CA 94063
21 .\"   <info@isc.org>
22 .\"   http://www.isc.org/
23 .\"
24 .\" This software has been written for Internet Systems Consortium
25 .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
26 .\" To learn more about Internet Systems Consortium, see
27 .\" ``http://www.isc.org/''.  To learn more about Vixie Enterprises,
28 .\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
29 .\" ``http://www.nominum.com''.
30 .TH omapi 3
31 .SH NAME
32 OMAPI - Object Management Application Programming Interface
33 .SH DESCRIPTION
34 .PP
35 OMAPI is an programming layer designed for controlling remote
36 applications, and for querying them for their state. It is currently
37 used by the ISC DHCP server and this outline addresses the parts of
38 OMAPI appropriate to the clients of DHCP server. It does this by also
39 describing the use of a thin API layered on top of OMAPI called
40 'dhcpctl'
41 .PP
42 OMAPI uses TCP/IP as the transport for server communication, and
43 security can be imposed by having the client and server
44 cryptographically sign messages using a shared secret.
45 .PP
46 dhcpctl works by presenting the client with handles to objects that
47 act as surrogates for the real objects in the server. For example a
48 client will create a handle for a lease object, and will request the
49 server to fill the lease handle's state. The client application can
50 then pull details such as the lease expiration time from the lease
51 handle. 
52 .PP
53 Modifications can be made to the server state by creating handles to
54 new objects, or by modifying attributes of handles to existing
55 objects, and then instructing the server to update itself according to
56 the changes made.
57 .SH USAGE
58 .PP
59 The client application must always call dhcpctl_initialize() before
60 making calls to any other dhcpctl functions. This initializes 
61 various internal data structures. 
62 .PP
63 To create the connection to the server the client must use
64 dhcpctl_connect() function. As well as making the physical connection
65 it will also set up the connection data structures to do
66 authentication on each message, if that is required.
67 .PP
68 All the dhcpctl functions return an integer value of type
69 isc_result_t. A successful call will yield a result of
70 ISC_R_SUCCESS. If the call fails for a reason local to the client
71 (e.g. insufficient local memory, or invalid arguments to the call)
72 then the return value of the dhcpctl function will show that. If the
73 call succeeds but the server couldn't process the request the error
74 value from the server is returned through another way, shown below.
75 .PP
76 The easiest way to understand dhcpctl is to see it in action. The
77 following program is fully functional, but almost all error checking
78 has been removed to make is shorter and easier to understand. This
79 program will query the server running on the localhost for the details
80 of the lease for IP address 10.0.0.101. It will then print out the time
81 the lease ends.
82 .PP
83 .nf
84                 #include <stdarg.h>
85                 #include <sys/time.h>
86                 #include <sys/socket.h>
87                 #include <stdio.h>
88                 #include <netinet/in.h>
89
90                 #include <isc/result.h>
91                 #include <dhcpctl/dhcpctl.h>
92
93                 int main (int argc, char **argv) {
94                         dhcpctl_data_string ipaddrstring = NULL;
95                         dhcpctl_data_string value = NULL;
96 .fi
97 .PP
98 All modifications of handles and all accesses of handle data happen
99 via dhcpctl_data_string objects.
100 .PP
101 .nf
102                         dhcpctl_handle connection = NULL;
103                         dhcpctl_handle lease = NULL;
104                         isc_result_t waitstatus;
105                         struct in_addr convaddr;
106                         time_t thetime;
107
108                         dhcpctl_initialize ();
109 .fi
110 .PP
111 Required first step.
112 .PP
113 .nf
114                         dhcpctl_connect (&connection, "127.0.0.1",
115                                          7911, 0);
116 .fi
117 .PP
118 Sets up the connection to the server. The server normally listens on
119 port 7911 unless configured to do otherwise.
120 .PP
121 .nf
122                         dhcpctl_new_object (&lease, connection,
123                                             "lease");
124 .fi
125 .PP
126 Here we create a handle to a lease. This call just sets up local data
127 structure. The server hasn't yet made any association between the
128 client's data structure and any lease it has.
129 .PP
130 .nf
131                         memset (&ipaddrstring, 0, sizeof
132                                 ipaddrstring);
133
134                         inet_pton(AF_INET, "10.0.0.101",
135                                   &convaddr);
136
137                         omapi_data_string_new (&ipaddrstring,
138                                                4, MDL);
139 .fi
140 .PP
141 Create a new data string to storing in the handle.
142 .PP
143 .nf
144                         memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
145
146                         dhcpctl_set_value (lease, ipaddrstring,
147                                            "ip-address");
148 .fi
149 .PP
150 We're setting the ip-address attribute of the lease handle to the
151 given address. We've not set any other attributes so when the server
152 makes the association the ip address will be all it uses to look up
153 the lease in its tables.
154 .PP
155 .nf
156                         dhcpctl_open_object (lease, connection, 0);
157 .fi
158 .PP
159 Here we prime the connection with the request to look up the lease in
160 the server and fill up the local handle with the attributes the server
161 will send over in its answer.
162 .PP
163 .nf
164                         dhcpctl_wait_for_completion (lease,
165                                                      &waitstatus);
166 .fi
167 .PP
168 This call causes the message to get sent to the server (the message to
169 look up the lease and send back the attribute values in the
170 answer). The value in the variable waitstatus when the function
171 returns will be the result from the server. If the message could
172 not be processed properly by the server then the error will be
173 reflected here.
174 .PP
175 .nf
176                         if (waitstatus != ISC_R_SUCCESS) {
177                                 /* server not authoritative */
178                                 exit (0);
179                         }
180
181                         dhcpctl_data_string_dereference(&ipaddrstring,
182                                                         MDL);
183 .fi
184 .PP
185 Clean-up memory we no longer need.
186 .PP
187 .nf
188                         dhcpctl_get_value (&value, lease, "ends");
189 .fi
190 .PP
191 Get the attribute named ``ends'' from the lease handle. This is a
192 4-byte integer of the time (in unix epoch seconds) that the lease
193 will expire.
194 .PP
195 .nf
196         
197                         memcpy(&thetime, value->value, value->len);
198                         dhcpctl_data_string_dereference(&value, MDL);
199
200                         fprintf (stdout, "ending time is %s",
201                                  ctime(&thetime));
202                 }
203
204 .fi
205 .SH AUTHENTICATION
206 If the server demands authenticated connections then before opening
207 the connection the user must call dhcpctl_new_authenticator.
208 .PP
209 .nf
210                 dhcpctl_handle authenticator = NULL;
211                 const char *keyname = "a-key-name";
212                 const char *algorithm = "hmac-md5";
213                 const char *secret = "a-shared-secret";
214
215                 dhcpctl_new_authenticator (&authenticator, 
216                                            keyname,
217                                            algorithm,
218                                            secret,
219                                            strlen(secret) + 1);
220 .fi
221 .PP
222 The keyname, algorithm and must all match what is specified in the server's
223 dhcpd.conf file, excepting that the secret should appear in 'raw' form, not
224 in base64 as it would in dhcpd.conf:
225 .PP
226 .nf
227                 key "a-key-name" {
228                         algorithm hmac-md5;
229                         secret "a-shared-secret";
230                 };
231
232                 # Set the omapi-key value to use
233                 # authenticated connections
234                 omapi-key a-key-name;
235 .fi
236 .PP
237 The authenticator handle that is created by the call to
238 dhcpctl_new_authenticator must be given as the last (the 4th) argument
239 to the call to dhcpctl_connect(). All messages will then be signed
240 with the given secret string using the specified algorithm.
241 .SH SEE ALSO
242 dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
243 .SH AUTHOR
244 .B omapi
245 was created by Ted Lemon of Nominum, Inc.  Information about Nominum
246 and support contracts for DHCP and BIND can be found at
247 .B http://www.nominum.com.   This documentation was written by James
248 Brister of Nominum, Inc.