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       ´dhcpctl´
15
16       OMAPI uses TCP/IP as the transport for server communication, and  secu‐
17       rity  can  be imposed by having the client and server cryptographically
18       sign messages using a shared secret.
19
20       dhcpctl works by presenting the client with handles to objects that act
21       as  surrogates for the real objects in the server. For example a client
22       will create a handle for a lease object, and will request the server to
23       fill  the  lease  handle's  state. The client application can then pull
24       details such as the lease expiration time from the lease handle.
25
26       Modifications can be made to the server state by  creating  handles  to
27       new objects, or by modifying attributes of handles to existing objects,
28       and then instructing the server  to  update  itself  according  to  the
29       changes made.
30

USAGE

32       The  client  application  must  always call dhcpctl_initialize() before
33       making calls to any other dhcpctl functions. This  initializes  various
34       internal data structures.
35
36       To create the connection to the server the client must use dhcpctl_con‐
37       nect() function. As well as making the physical connection it will also
38       set up the connection data structures to do authentication on each mes‐
39       sage, if that is required.
40
41       All the dhcpctl functions return an integer value of type isc_result_t.
42       A  successful  call  will  yield a result of ISC_R_SUCCESS. If the call
43       fails for a reason local to the client (e.g. insufficient local memory,
44       or  invalid arguments to the call) then the return value of the dhcpctl
45       function will show that. If the call succeeds but the  server  couldn't
46       process the request the error value from the server is returned through
47       another way, shown below.
48
49       The easiest way to understand dhcpctl is to see it in action. The  fol‐
50       lowing  program  is fully functional, but almost all error checking has
51       been removed to make is shorter and easier to understand. This  program
52       will  query  the server running on the localhost for the details of the
53       lease for IP address 10.0.0.101. It will then print out  the  time  the
54       lease ends.
55
56                 #include <stdarg.h>
57                 #include <sys/time.h>
58                 #include <sys/socket.h>
59                 #include <stdio.h>
60                 #include <netinet/in.h>
61
62                 #include <isc/result.h>
63                 #include <dhcpctl/dhcpctl.h>
64
65                 int main (int argc, char **argv) {
66                      dhcpctl_data_string ipaddrstring = NULL;
67                      dhcpctl_data_string value = NULL;
68
69       All modifications of handles and all accesses of handle data happen via
70       dhcpctl_data_string objects.
71
72                      dhcpctl_handle connection = NULL;
73                      dhcpctl_handle lease = NULL;
74                      isc_result_t waitstatus;
75                      struct in_addr convaddr;
76                      time_t thetime;
77
78                      dhcpctl_initialize ();
79
80       Required first step.
81
82                      dhcpctl_connect (&connection, "127.0.0.1",
83                                 7911, 0);
84
85       Sets up the connection to the server. The server  normally  listens  on
86       port 7911 unless configured to do otherwise.
87
88                      dhcpctl_new_object (&lease, connection,
89                                    "lease");
90
91       Here  we  create a handle to a lease. This call just sets up local data
92       structure. The server hasn't  yet  made  any  association  between  the
93       client's data structure and any lease it has.
94
95                      memset (&ipaddrstring, 0, sizeof
96                           ipaddrstring);
97
98                      inet_pton(AF_INET, "10.0.0.101",
99                             &convaddr);
100
101                      omapi_data_string_new (&ipaddrstring,
102                                       4, MDL);
103
104       Create a new data string to storing in the handle.
105
106                      memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
107
108                      dhcpctl_set_value (lease, ipaddrstring,
109                                   "ip-address");
110
111       We're setting the ip-address attribute of the lease handle to the given
112       address. We've not set any other attributes so when  the  server  makes
113       the association the ip address will be all it uses to look up the lease
114       in its tables.
115
116                      dhcpctl_open_object (lease, connection, 0);
117
118       Here we prime the connection with the request to look up the  lease  in
119       the  server and fill up the local handle with the attributes the server
120       will send over in its answer.
121
122                      dhcpctl_wait_for_completion (lease,
123                                          &waitstatus);
124
125       This call causes the message to get sent to the server (the message  to
126       look  up  the  lease and send back the attribute values in the answer).
127       The value in the variable waitstatus when the function returns will  be
128       the result from the server. If the message could not be processed prop‐
129       erly by the server then the error will be reflected here.
130
131                      if (waitstatus != ISC_R_SUCCESS) {
132                           /* server not authoritative */
133                           exit (0);
134                      }
135
136                      dhcpctl_data_string_dereference(&ipaddrstring,
137                                          MDL);
138
139       Clean-up memory we no longer need.
140
141                      dhcpctl_get_value (&value, lease, "ends");
142
143       Get the attribute named ``ends'' from  the  lease  handle.  This  is  a
144       4-byte  integer of the time (in unix epoch seconds) that the lease will
145       expire.
146
147
148                      memcpy(&thetime, value->value, value->len);
149                      dhcpctl_data_string_dereference(&value, MDL);
150
151                      fprintf (stdout, "ending time is %s",
152                            ctime(&thetime));
153                 }
154
155

AUTHENTICATION

157       If the server demands authenticated connections then before opening the
158       connection the user must call dhcpctl_new_authenticator.
159
160                 dhcpctl_handle authenticator = NULL;
161                 const char *keyname = "a-key-name";
162                 const char *algorithm = "hmac-md5";
163                 const char *secret = "a-shared-secret";
164
165                 dhcpctl_new_authenticator (&authenticator,
166                                                  keyname,
167                                                  algorithm,
168                                                  secret,
169                                   strlen(secret) + 1);
170
171       The  keyname,  algorithm  and  must  all match what is specified in the
172       server's dhcpd.conf file, excepting that the secret  should  appear  in
173       ´raw´ form, not in base64 as it would in dhcpd.conf:
174
175                 key "a-key-name" {
176                      algorithm hmac-md5;
177                      secret "a-shared-secret";
178                 };
179
180                 # Set the omapi-key value to use
181                 # authenticated connections
182                 omapi-key a-key-name;
183
184       The   authenticator   handle   that   is   created   by   the  call  to
185       dhcpctl_new_authenticator must be given as the last (the 4th)  argument
186       to the call to dhcpctl_connect(). All messages will then be signed with
187       the given secret string using the specified algorithm.
188

SEE ALSO

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

AUTHOR

194       omapi  is maintained by ISC.  To learn more about Internet Systems Con‐
195       sortium, see https://www.isc.org
196
197
198
199
200                                                                      omapi(3)
Impressum