From: Ben Cottrell Date: Thu, 12 Apr 2001 21:23:14 +0000 (+0000) Subject: Arf... these are nroff output, but I don't have the original troff source. X-Git-Tag: V3-RC1~14 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=dc6d4b5a3ea714cc2210a7845607a3c165a98ada;p=thirdparty%2Fdhcp.git Arf... these are nroff output, but I don't have the original troff source. Hopefully James does, so he can replace these with the nroff. I just used: memcpy(ipaddrstring->value, &convaddr.s_addr, 4); for the byte order thingy. I'm hoping this is right. inet_pton will spit out the address in network byte order, and Ted says that dhcpctl_set_value is expecting it in network byte order, also. --- diff --git a/dhcpctl/dhcpctl.3 b/dhcpctl/dhcpctl.3 index e69de29bb..5597c58de 100644 --- a/dhcpctl/dhcpctl.3 +++ b/dhcpctl/dhcpctl.3 @@ -0,0 +1,268 @@ +DHCPCTL(3) DHCP Programmer's Manual DHCPCTL(3) + +NAME + dhcpctl_initialize - dhcpctl library initialization. + +SYNOPSIS + #include + + + dhcpctl_status + dhcpctl_initialize(void); + + dhcpctl_status + dhcpctl_connect(dhcpctl_handle *cxn, const char *host, int port, + dhcpctl_handle auth); + + dhcpctl_status + dhcpctl_wait_for_completion(dhcpctl_handle object, + dhcpctl_status *status); + + dhcpctl_status + dhcpctl_get_value(dhcpctl_data_string *value, dhcpctl_handle object, + const char *name); + + dhcpctl_status + dhcpctl_get_boolean(int *value, dhcpctl_handle object, const char *name); + + dhcpctl_status + dhcpctl_set_value(dhcpctl_handle object, dhcpctl_data_string value, + const char *name); + + dhcpctl_status + dhcpctl_set_string_value(dhcpctl_handle object, const char *value, + const char *name); + + dhcpctl_status + dhcpctl_set_boolean_value(dhcpctl_handle object, int value, + const char *name); + + dhcpctl_status + dhcpctl_set_int_value(dhcpctl_handle object, int value, + const char *name); + + dhcpctl_status + dhcpctl_object_update(dhcpctl_handle connection, dhcpctl_handle object); + + dhcpctl_status + dhcpctl_object_refresh(dhcpctl_handle connection, dhcpctl_handle object); + + dhcpctl_status + dhcpctl_object_remove(dhcpctl_handle connection, dhcpctl_handle object); + + dhcpctl_status + dhcpctl_set_callback(dhcpctl_handle object, void *data, + void (*function) (dhcpctl_handle, dhcpctl_status, void *)); + + dhcpctl_status + dhcpctl_new_authenticator(dhcpctl_handle *object, const char *name, + const char *algorithm, const char *secret, unsigned secret_len); + + dhcpctl_status + dhcpctl_new_object(dhcpctl_handle *object, dhcpctl_handle connection, + const char *object_type); + + + dhcpctl_status + dhcpctl_open_object(dhcpctl_handle object, dhcpctl_handle connection, + int flags); + + isc_result_t + omapi_data_string_new(dhcpctl_data_string, *data, unsigned, int, length, + const, char, *filename,, int, lineno); + + isc_result_t + dhcpctl_data_string_dereference(dhcpctl_data_string *, const char *, + int); + +DESCRIPTION + The dhcpctl set of functions provide an API that can be used to communi + cate with and manipulate a running ISC DHCP server. All functions return + a value of isc_result_t. The return values reflects the result of opera + tions to local data structures. If an operation fails on the server for + any reason, then the error result will be returned through the second pa + rameter of the dhcpctl_wait_for_completion() call. + + dhcpctl_initialize() sets up the data structures the library needs to do + its work. This function must be called once before any other. + + dhcpctl_connect() opens a connection to the DHCP server at the given host + and port. If an authenticator has been created for the connection, then + it is given as the 4th argument. On a successful return the address + pointed at by the first argument will have a new connection object as + signed to it. + + For example: + + s =3D dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL); + + connects to the DHCP server on the localhost via port 7911 (the standard + OMAPI port). No authentication is used for the connection. + + dhcpctl_wait_for_completion() flushes a pending message to the server and + waits for the response. The result of the request as processed on the + server is returned via the second parameter. + + s =3D dhcpctl_wait_for_completion(cxn, &wv); + if (s !=3D ISC_R_SUCCESS) + local_failure(s); + else if (wv !=3D ISC_R_SUCCESS) + server_failure(wc); + + The call to dhcpctl_wait_for_completion() won't return until the remote + message processing completes or the connection to the server is lost. + + dhcpctl_get_value() extracts a value of an attribute from the handle. The + value can be of any length and is treated as a sequence of bytes. The + handle must have been created first with dhcpctl_new_object() and opened + with dhcpctl_open_object(). The value is returned via the parameter + named ``value''. The last parameter is the name of attribute to retrieve. + + dhcpctl_data_string value =3D NULL; + dhcpctl_handle lease; + time_t thetime; + + s =3D dhcpctl_get_value (&value, lease, "ends"); + assert(s =3D=3D ISC_R_SUCCESS && value->len =3D=3D sizeof(thetime)); + memcpy(&thetime, value->value, value->len); + + dhcpctl_get_boolean() extracts a boolean valued attribute from the object + handle. + + + The dhcpctl_set_value(), dhcpctl_set_string_value(), + dhcpctl_set_boolean_value(), and dhcpctl_set_int_value() functions all + set a value on the object handle. + + dhcpctl_object_update() function queues a request for all the changes + made to the object handle be be sent to the remote for processing. The + changes made to the atributes on the handle will be applied to remote ob + ject if permitted. + + dhcpctl_object_refresh() queues up a request for a fresh copy of all the + attribute values to be sent from the remote to refresh the values in the + local object handle. + + dhcpctl_object_remove() queues a request for the removal on the server of + the object referenced by the handle. + + The dhcpctl_set_callback() function sets up a user-defined function to be + called when an event completes on the given object handle. This is needed + for asynchronous handling of events, versus the synchronous handling giv + en by dhcpctl_wait_for_completion(). When the function is called the + first parameter is the object the event arrived for, the second is the + status of the message that was processed, the third is the same value as + the second parameter given to dhcpctl_set_callback(). + + The dhcpctl_new_authenticator() creates a new authenticator object to be + used for signing the messages that cross over the network. The ``name'', + ``algorithm'', and ``secret'' values must all match what the server uses + and are defined in its configuration file. The created object is returned + through the first parameter and must be used as the 4th parameter to + dhcpctl_connect(). + + dhcpctl_new_object() creates a local handle for an object on the the + server. The ``object_type'' parameter is the ascii name of the type of + object being accessed. e.g. "lease". This function only sets up local + data structures, it does not queue any messages to be sent to the remote + side, dhcpctl_open_object() does that. + + dhcpctl_open_object() builds and queues the request to the remote side. + This function is used with handle created via dhcpctl_new_object(). The + flags argument is a bit mask with the following values available for set + ting: + + DHCPCTL_CREATE + if the object does not exist then the remote will create it + + DHCPCTL_UPDATE + update the object on the remote side using the attributes al + ready set in the handle. + + DHCPCTL_EXCL + return and error if the object exists and DHCPCTL_CREATE was al + so specified + + The omapi_data_string_new() function allocates a new dhcpctl_data_string + object. The data string will be large enough to hold ``length'' bytes of + data. The ``file'' and ``lineno'' arguments are the source file location + the call is made from, typically by using the __FILE__ and __LINE__ + macros or the MDL macro defined in + + dhcpctl_data_string_dereference() deallocates a data string created by + omapi_data_string_new(). The memory for the object won't be compelely + deallocated until the last reference is released. + +EXAMPLES + + The following program will connect to the DHCP server running on the lo + cal host and will get the details of the existing lease for IP address + 10.0.0.101. It will then print out the time the lease is due to expire. + Note that most error checking has been ommitted for brevity. + + #include + #include + #include + #include + #include + + #include + #include + + int main (int argc, char **argv) { + dhcpctl_data_string ipaddrstring =3D NULL; + dhcpctl_data_string value =3D NULL; + dhcpctl_handle connection =3D NULL; + dhcpctl_handle lease =3D NULL; + isc_result_t waitstatus; + struct in_addr convaddr; + time_t thetime; + + dhcpctl_initialize (); + + dhcpctl_connect (&connection, "127.0.0.1", + 7911, 0); + + dhcpctl_new_object (&lease, connection, + "lease"); + + memset (&ipaddrstring, 0, sizeof + ipaddrstring); + + inet_pton(AF_INET, "10.0.0.101", + &convaddr); + + omapi_data_string_new (&ipaddrstring, + 4, MDL); + memcpy(ipaddrstring->value, &convaddr.s_addr, 4); + + dhcpctl_set_value (lease, ipaddrstring, + "ip-address"); + + dhcpctl_open_object (lease, connection, 0); + + dhcpctl_wait_for_completion (lease, + &waitstatus); + if (waitstatus !=3D ISC_R_SUCCESS) { + /* server not authoritative */ + exit (0); + } + + dhcpctl_data_string_dereference(&ipaddrstring, + MDL); + + dhcpctl_get_value (&value, lease, "ends"); + + memcpy(&thetime, value->value, value->len); + + dhcpctl_data_string_dereference(&value, MDL); + + fprintf (stdout, "ending time is %s", + ctime(&thetime)); + } + +SEE ALSO + omapi-intro(1) + + DHCP Nov 15, 2000 5 + diff --git a/omapip/omapi.3 b/omapip/omapi.3 index e69de29bb..eacb9da33 100644 --- a/omapip/omapi.3 +++ b/omapip/omapi.3 @@ -0,0 +1,192 @@ +NAME + OMAPI - Object Management Application Programming Interface + +DESCRIPTION + +Overview + + 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' + + 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. + + 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. + + 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. + +Usage + + The client application must always call dhcpctl_initialize() before + making calls to any other dhcpctl functions. This initializes + various internal data structures. + + 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. + + 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. + + 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. + + #include + #include + #include + #include + #include + + #include + #include + + int main (int argc, char **argv) { + dhcpctl_data_string ipaddrstring = NULL; + dhcpctl_data_string value = NULL; + + All modifications of handles and all accesses of handle data happen + via dhcpctl_data_string objects. + + dhcpctl_handle connection = NULL; + dhcpctl_handle lease = NULL; + isc_result_t waitstatus; + struct in_addr convaddr; + time_t thetime; + + dhcpctl_initialize (); + + Required fist step. + + dhcpctl_connect (&connection, "127.0.0.1", + 7911, 0); + + Sets up the connection to the server. The server normally listens on + port 7911 unless configured to do otherwise. + + dhcpctl_new_object (&lease, connection, + "lease"); + + 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. + + memset (&ipaddrstring, 0, sizeof + ipaddrstring); + + inet_pton(AF_INET, "10.0.0.101", + &convaddr); + + omapi_data_string_new (&ipaddrstring, + 4, MDL); + + Create a new data string to storing in the handle. + + memcpy(ipaddrstring->value, &convaddr.s_addr, 4); + + dhcpctl_set_value (lease, ipaddrstring, + "ip-address"); + + 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. + + dhcpctl_open_object (lease, connection, 0); + + 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. + + dhcpctl_wait_for_completion (lease, + &waitstatus); + + 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. + + if (waitstatus != ISC_R_SUCCESS) { + /* server not authoritative */ + exit (0); + } + + dhcpctl_data_string_dereference(&ipaddrstring, + MDL); + + Clean-up memory we no longer need. + + dhcpctl_get_value (&value, lease, "ends"); + + 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. + + memcpy(&thetime, value->value, value->len); + dhcpctl_data_string_dereference(&value, MDL); + + fprintf (stdout, "ending time is %s", + ctime(&thetime)); + } + + +Authentication + + If the server demands authenticated connections then before opening + the connection the user must call dhcpctl_new_authenticator. + + 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); + + The keyname, algorithm and secret must all match what is specified in + the server's dhcpd.conf file: + + 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"; + + 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. + +SEE ALSO + + dhcpctl(3)