external/bsd/dhcp/dist/omapip/omapi.3

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