1omapi(3)                   Library Functions Manual                   omapi(3)
2
3
4

NAME

6       OMAPI - Object Management Application Programming Interface
7

DESCRIPTION

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
15       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
19       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
25       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

USAGE

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
35       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
40       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
48       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
55                 #include <stdarg.h>
56                 #include <sys/time.h>
57                 #include <sys/socket.h>
58                 #include <stdio.h>
59                 #include <netinet/in.h>
60
61                 #include <isc/result.h>
62                 #include <dhcpctl/dhcpctl.h>
63
64                 int main (int argc, char **argv) {
65                      dhcpctl_data_string ipaddrstring = NULL;
66                      dhcpctl_data_string value = NULL;
67
68       All modifications of handles and all accesses of handle data happen via
69       dhcpctl_data_string objects.
70
71                      dhcpctl_handle connection = NULL;
72                      dhcpctl_handle lease = NULL;
73                      isc_result_t waitstatus;
74                      struct in_addr convaddr;
75                      time_t thetime;
76
77                      dhcpctl_initialize ();
78
79       Required first step.
80
81                      dhcpctl_connect (&connection, "127.0.0.1",
82                                 7911, 0);
83
84       Sets  up  the  connection to the server. The server normally listens on
85       port 7911 unless configured to do otherwise.
86
87                      dhcpctl_new_object (&lease, connection,
88                                    "lease");
89
90       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
94                      memset (&ipaddrstring, 0, sizeof
95                           ipaddrstring);
96
97                      inet_pton(AF_INET, "10.0.0.101",
98                             &convaddr);
99
100                      omapi_data_string_new (&ipaddrstring,
101                                       4, MDL);
102
103       Create a new data string to storing in the handle.
104
105                      memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
106
107                      dhcpctl_set_value (lease, ipaddrstring,
108                                   "ip-address");
109
110       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
115                      dhcpctl_open_object (lease, connection, 0);
116
117       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
121                      dhcpctl_wait_for_completion (lease,
122                                          &waitstatus);
123
124       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
130                      if (waitstatus != ISC_R_SUCCESS) {
131                           /* server not authoritative */
132                           exit (0);
133                      }
134
135                      dhcpctl_data_string_dereference(&ipaddrstring,
136                                          MDL);
137
138       Clean-up memory we no longer need.
139
140                      dhcpctl_get_value (&value, lease, "ends");
141
142       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
146
147                      memcpy(&thetime, value->value, value->len);
148                      dhcpctl_data_string_dereference(&value, MDL);
149
150                      fprintf (stdout, "ending time is %s",
151                            ctime(&thetime));
152                 }
153
154

AUTHENTICATION

156       If the server demands authenticated connections then before opening the
157       connection the user must call dhcpctl_new_authenticator.
158
159                 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
164                 dhcpctl_new_authenticator (&authenticator,
165                                                  keyname,
166                                                  algorithm,
167                                                  secret,
168                                   strlen(secret) + 1);
169
170       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
174                 key "a-key-name" {
175                      algorithm hmac-md5;
176                      secret "a-shared-secret";
177                 };
178
179                 # Set the omapi-key value to use
180                 # authenticated connections
181                 omapi-key a-key-name;
182
183       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

SEE ALSO

189       dhcpctl(3),    omshell(1),    dhcpd(8),   dhclient(8),   dhcpd.conf(5),
190       dhclient.conf(5).
191

AUTHOR

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
198
199
200                                                                      omapi(3)
Impressum