]>
Commit | Line | Data |
---|---|---|
d758ad8c TL |
1 | .\" omapi.3 |
2 | .\" | |
98311e4b DH |
3 | .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") |
4 | .\" Copyright (c) 2000-2003 by Internet Software Consortium | |
d758ad8c | 5 | .\" |
98311e4b DH |
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. | |
d758ad8c | 9 | .\" |
98311e4b DH |
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. | |
d758ad8c | 17 | .\" |
98311e4b DH |
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 | |
d758ad8c | 25 | .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. |
98311e4b | 26 | .\" To learn more about Internet Systems Consortium, see |
d758ad8c TL |
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 | |
dc6d4b5a BC |
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; | |
d758ad8c TL |
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 | |
dc6d4b5a BC |
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 (); | |
d758ad8c TL |
109 | .fi |
110 | .PP | |
111 | Required first step. | |
112 | .PP | |
113 | .nf | |
dc6d4b5a BC |
114 | dhcpctl_connect (&connection, "127.0.0.1", |
115 | 7911, 0); | |
d758ad8c TL |
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 | |
dc6d4b5a BC |
122 | dhcpctl_new_object (&lease, connection, |
123 | "lease"); | |
d758ad8c TL |
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 | |
dc6d4b5a BC |
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); | |
d758ad8c TL |
139 | .fi |
140 | .PP | |
141 | Create a new data string to storing in the handle. | |
142 | .PP | |
143 | .nf | |
dc6d4b5a BC |
144 | memcpy(ipaddrstring->value, &convaddr.s_addr, 4); |
145 | ||
146 | dhcpctl_set_value (lease, ipaddrstring, | |
147 | "ip-address"); | |
d758ad8c TL |
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 | |
dc6d4b5a | 156 | dhcpctl_open_object (lease, connection, 0); |
d758ad8c TL |
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 | |
dc6d4b5a BC |
164 | dhcpctl_wait_for_completion (lease, |
165 | &waitstatus); | |
d758ad8c TL |
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 | |
dc6d4b5a BC |
176 | if (waitstatus != ISC_R_SUCCESS) { |
177 | /* server not authoritative */ | |
178 | exit (0); | |
179 | } | |
180 | ||
181 | dhcpctl_data_string_dereference(&ipaddrstring, | |
182 | MDL); | |
d758ad8c TL |
183 | .fi |
184 | .PP | |
185 | Clean-up memory we no longer need. | |
186 | .PP | |
187 | .nf | |
dc6d4b5a | 188 | dhcpctl_get_value (&value, lease, "ends"); |
d758ad8c TL |
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 | |
dc6d4b5a BC |
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 | ||
d758ad8c TL |
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 | |
dc6d4b5a BC |
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); | |
d758ad8c TL |
220 | .fi |
221 | .PP | |
98311e4b DH |
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: | |
d758ad8c TL |
225 | .PP |
226 | .nf | |
dc6d4b5a BC |
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 | |
98311e4b | 234 | omapi-key a-key-name; |
d758ad8c TL |
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. |