1: .\" omapi.3
2: .\"
3: .\" Copyright (c) 2009-2010 by Internet Systems Consortium, Inc. ("ISC")
4: .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
5: .\" Copyright (c) 2000-2003 by Internet Software Consortium
6: .\"
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.
10: .\"
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.
18: .\"
19: .\" Internet Systems Consortium, Inc.
20: .\" 950 Charter Street
21: .\" Redwood City, CA 94063
22: .\" <info@isc.org>
23: .\" https://www.isc.org/
24: .\"
25: .\" This software has been written for Internet Systems Consortium
26: .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
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: .\"
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
41: \'dhcpctl\'
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
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;
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
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 ();
110: .fi
111: .PP
112: Required first step.
113: .PP
114: .nf
115: dhcpctl_connect (&connection, "127.0.0.1",
116: 7911, 0);
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
123: dhcpctl_new_object (&lease, connection,
124: "lease");
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
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);
140: .fi
141: .PP
142: Create a new data string to storing in the handle.
143: .PP
144: .nf
145: memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
146:
147: dhcpctl_set_value (lease, ipaddrstring,
148: "ip-address");
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
157: dhcpctl_open_object (lease, connection, 0);
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
165: dhcpctl_wait_for_completion (lease,
166: &waitstatus);
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
177: if (waitstatus != ISC_R_SUCCESS) {
178: /* server not authoritative */
179: exit (0);
180: }
181:
182: dhcpctl_data_string_dereference(&ipaddrstring,
183: MDL);
184: .fi
185: .PP
186: Clean-up memory we no longer need.
187: .PP
188: .nf
189: dhcpctl_get_value (&value, lease, "ends");
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
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:
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
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);
221: .fi
222: .PP
223: The keyname, algorithm and must all match what is specified in the server's
224: dhcpd.conf file, excepting that the secret should appear in \'raw\' form, not
225: in base64 as it would in dhcpd.conf:
226: .PP
227: .nf
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
235: omapi-key a-key-name;
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
243: dhcpctl(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
244: .SH AUTHOR
245: .B omapi
246: was created by Ted Lemon of Nominum, Inc. This documentation was
247: written by James Brister of Nominum, Inc.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to omapi.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / omapip