diff options
Diffstat (limited to 'contrib/isc-dhcp/omapip/omapi.3')
| -rw-r--r-- | contrib/isc-dhcp/omapip/omapi.3 | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/contrib/isc-dhcp/omapip/omapi.3 b/contrib/isc-dhcp/omapip/omapi.3 new file mode 100644 index 000000000000..112621df3fd1 --- /dev/null +++ b/contrib/isc-dhcp/omapip/omapi.3 @@ -0,0 +1,254 @@ +.\" omapi.3 +.\" +.\" Copyright (c) 2000-2001 Internet Software Consortium. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of The Internet Software Consortium nor the names +.\" of its contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND +.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR +.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" This software has been written for the Internet Software Consortium +.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. +.\" To learn more about the Internet Software Consortium, see +.\" ``http://www.isc.org/''. To learn more about Vixie Enterprises, +.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see +.\" ``http://www.nominum.com''. +.TH omapi 3 +.SH NAME +OMAPI - Object Management Application Programming Interface +.SH DESCRIPTION +.PP +OMAPI is an programming layer designed for controlling remote +applications, and for querying them for their state. It is currently +used by the ISC DHCP server and this outline addresses the parts of +OMAPI appropriate to the clients of DHCP server. It does this by also +describing the use of a thin API layered on top of OMAPI called +'dhcpctl' +.PP +OMAPI uses TCP/IP as the transport for server communication, and +security can be imposed by having the client and server +cryptographically sign messages using a shared secret. +.PP +dhcpctl works by presenting the client with handles to objects that +act as surrogates for the real objects in the server. For example a +client will create a handle for a lease object, and will request the +server to fill the lease handle's state. The client application can +then pull details such as the lease expiration time from the lease +handle. +.PP +Modifications can be made to the server state by creating handles to +new objects, or by modifying attributes of handles to existing +objects, and then instructing the server to update itself according to +the changes made. +.SH USAGE +.PP +The client application must always call dhcpctl_initialize() before +making calls to any other dhcpctl functions. This initializes +various internal data structures. +.PP +To create the connection to the server the client must use +dhcpctl_connect() function. As well as making the physical connection +it will also set up the connection data structures to do +authentication on each message, if that is required. +.PP +All the dhcpctl functions return an integer value of type +isc_result_t. A successful call will yield a result of +ISC_R_SUCCESS. If the call fails for a reason local to the client +(e.g. insufficient local memory, or invalid arguments to the call) +then the return value of the dhcpctl function will show that. If the +call succeeds but the server couldn't process the request the error +value from the server is returned through another way, shown below. +.PP +The easiest way to understand dhcpctl is to see it in action. The +following program is fully functional, but almost all error checking +has been removed to make is shorter and easier to understand. This +program will query the server running on the localhost for the details +of the lease for IP address 10.0.0.101. It will then print out the time +the lease ends. +.PP +.nf + #include <stdarg.h> + #include <sys/time.h> + #include <sys/socket.h> + #include <stdio.h> + #include <netinet/in.h> + + #include <isc/result.h> + #include <dhcpctl/dhcpctl.h> + + int main (int argc, char **argv) { + dhcpctl_data_string ipaddrstring = NULL; + dhcpctl_data_string value = NULL; +.fi +.PP +All modifications of handles and all accesses of handle data happen +via dhcpctl_data_string objects. +.PP +.nf + dhcpctl_handle connection = NULL; + dhcpctl_handle lease = NULL; + isc_result_t waitstatus; + struct in_addr convaddr; + time_t thetime; + + dhcpctl_initialize (); +.fi +.PP +Required first step. +.PP +.nf + dhcpctl_connect (&connection, "127.0.0.1", + 7911, 0); +.fi +.PP +Sets up the connection to the server. The server normally listens on +port 7911 unless configured to do otherwise. +.PP +.nf + dhcpctl_new_object (&lease, connection, + "lease"); +.fi +.PP +Here we create a handle to a lease. This call just sets up local data +structure. The server hasn't yet made any association between the +client's data structure and any lease it has. +.PP +.nf + memset (&ipaddrstring, 0, sizeof + ipaddrstring); + + inet_pton(AF_INET, "10.0.0.101", + &convaddr); + + omapi_data_string_new (&ipaddrstring, + 4, MDL); +.fi +.PP +Create a new data string to storing in the handle. +.PP +.nf + memcpy(ipaddrstring->value, &convaddr.s_addr, 4); + + dhcpctl_set_value (lease, ipaddrstring, + "ip-address"); +.fi +.PP +We're setting the ip-address attribute of the lease handle to the +given address. We've not set any other attributes so when the server +makes the association the ip address will be all it uses to look up +the lease in its tables. +.PP +.nf + dhcpctl_open_object (lease, connection, 0); +.fi +.PP +Here we prime the connection with the request to look up the lease in +the server and fill up the local handle with the attributes the server +will send over in its answer. +.PP +.nf + dhcpctl_wait_for_completion (lease, + &waitstatus); +.fi +.PP +This call causes the message to get sent to the server (the message to +look up the lease and send back the attribute values in the +answer). The value in the variable waitstatus when the function +returns will be the result from the server. If the message could +not be processed properly by the server then the error will be +reflected here. +.PP +.nf + if (waitstatus != ISC_R_SUCCESS) { + /* server not authoritative */ + exit (0); + } + + dhcpctl_data_string_dereference(&ipaddrstring, + MDL); +.fi +.PP +Clean-up memory we no longer need. +.PP +.nf + dhcpctl_get_value (&value, lease, "ends"); +.fi +.PP +Get the attribute named ``ends'' from the lease handle. This is a +4-byte integer of the time (in unix epoch seconds) that the lease +will expire. +.PP +.nf + + memcpy(&thetime, value->value, value->len); + dhcpctl_data_string_dereference(&value, MDL); + + fprintf (stdout, "ending time is %s", + ctime(&thetime)); + } + +.fi +.SH AUTHENTICATION +If the server demands authenticated connections then before opening +the connection the user must call dhcpctl_new_authenticator. +.PP +.nf + dhcpctl_handle authenticator = NULL; + const char *keyname = "a-key-name"; + const char *algorithm = "hmac-md5"; + const char *secret = "a-shared-secret"; + + dhcpctl_new_authenticator (&authenticator, + keyname, + algorithm, + secret, + strlen(secret) + 1); +.fi +.PP +The keyname, algorithm and secret must all match what is specified in +the server's dhcpd.conf file: +.PP +.nf + key "a-key-name" { + algorithm hmac-md5; + secret "a-shared-secret"; + }; + + # Set the omapi-key value to use + # authenticated connections + omapi-key "a-key-name"; +.fi +.PP +The authenticator handle that is created by the call to +dhcpctl_new_authenticator must be given as the last (the 4th) argument +to the call to dhcpctl_connect(). All messages will then be signed +with the given secret string using the specified algorithm. +.SH SEE ALSO +dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5). +.SH AUTHOR +.B omapi +was created by Ted Lemon of Nominum, Inc. Information about Nominum +and support contracts for DHCP and BIND can be found at +.B http://www.nominum.com. This documentation was written by James +Brister of Nominum, Inc. |