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