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