diff options
Diffstat (limited to 'omapip/omapi.3')
-rw-r--r-- | omapip/omapi.3 | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/omapip/omapi.3 b/omapip/omapi.3 new file mode 100644 index 0000000..4868d7c --- /dev/null +++ b/omapip/omapi.3 @@ -0,0 +1,247 @@ +.\" omapi.3 +.\" +.\" Copyright (c) 2009-2010 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 2000-2003 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Internet Systems Consortium, Inc. +.\" 950 Charter Street +.\" Redwood City, CA 94063 +.\" <info@isc.org> +.\" https://www.isc.org/ +.\" +.\" This software has been written for Internet Systems Consortium +.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. +.\" +.\" Support and other services are available for ISC products - see +.\" https://www.isc.org for more information or to learn more about ISC. +.\" +.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 must all match what is specified in the server's +dhcpd.conf file, excepting that the secret should appear in \'raw\' form, not +in base64 as it would in dhcpd.conf: +.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), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5). +.SH AUTHOR +.B omapi +was created by Ted Lemon of Nominum, Inc. This documentation was +written by James Brister of Nominum, Inc. |