255 lines
8.6 KiB
Groff
255 lines
8.6 KiB
Groff
.\" 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.
|