contrib/isc-dhcp/omapip/omapi.3

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