![[Contents]](icons/contents.gif){kind=icon}
![[Index]](icons/index.gif){kind=icon}
![[Top]](icons/top.gif){kind=icon}
![[Prev]](icons/prev.gif){kind=icon}
![[Next]](icons/next.gif){kind=icon}
DHCP, an extension of BOOTP, is designed to supply clients with all of the Internet configuration parameters defined in the Host Requirements documents (RFCs 1122 and 1123) without manual intervention. Like BOOTP, DHCP allows the permanent allocation of configuration parameters to specific clients. However, DHCP also supports the assignment of a network address for a finite lease period. This feature allows serial reassignment of network addresses. The DHCP implementation provided with VxWorks conforms to the Internet standard RFC 1541.
VxWorks includes a DHCP client, server, and relay agent. The DHCP client can retrieve one or more sets of configuration parameters from either a DHCP or BOOTP server. The DHCP client also maintains any leases it has retrieved. Likewise, the DHCP server can process both BOOTP and DHCP messages. Both the client and server implementations support all options described in RFC 1533. The DHCP relay agent provides forwarding of DHCP and BOOTP messages across subnet boundaries. 1
If the server is configured to provide them, a lease can include configuration parameters in addition to an assigned IP address . To minimize network traffic, the DHCP client sets configuration values to the defaults specified in the Host Requirements documents (RFCs 1122 and 1123) if the corresponding parameters are not specified by the server.
Unlike the configuration parameters supplied by BOOTP, the DHCP-assigned configuration parameters can expire. Although the DHCP server can duplicate BOOTP behavior and issue a permanent IP address to the client, the lease granted is usually temporary. To continue using the assigned parameters, the client must periodically contact the issuing server to renew the lease.
|
WARNING: The Tornado tools do not currently have any way to discover or respond to a change in the target's IP address. Such a change breaks the network connection. In response, you must manually reconnect the Tornado tools to the target's new IP address. During development, this is rarely a serious problem, and you can avoid it by having the DHCP server issue an infinite lease on the target's IP address.
|
||||||||||||||||||
To control which DHCP feature VxWorks includes, you must reconfigure VxWorks. The relevant configuration macro is found in the list below:
You can configure VxWorks to set these parameters to any desired value. However, the DHCP client rejects all offers whose duration is less than the minimum lease. Therefore, setting the DHCP Client Minimum Lease value too high could prevent the retrieval of any configuration parameters. In addition, if the DHCP client is used at boot time, the values for DHCP Client Target Port and DHCP Client Host Port used in the boot program and run-time image must match.
Finally, the DHCP Client Maximum Leases limit on multiple concurrent leases includes a lease established at boot time. For example, if this limit has a value of four, and if a boot-time DHCP client retrieves a lease, the run-time DHCP client is limited to three additional sets of configuration parameters (until the boot-time lease expires).
For more information on using a DHCP client to retrieve network configuration parameters at boot-time, see 13. Booting over the Network.
|
NOTE: In addition to setting values for the defines mentioned above, most real-world uses of DHCP require that you provide an event hook routine to handle lease events. For more information, see the dhcpcEventHookAdd( ) reference entry.
|
||||||||||||||||||
Configuring the DHCP server requires that you create a pool of configuration parameter sets. Each parameter set must include an IP address. When a DHCP client makes a request of the server, the server can then assign a parameter set to the client (either permanently or on a leased basis). To store and maintain this pool of configuration parameter sets, some DHCP servers use one or more files. This approach is analogous to the use of the bootptab file associated with SunOS BOOTP servers. The unsupported DHCP server distributed with VxWorks takes this approach.
However, some VxWorks targets do not include a file system. The supported target-resident DHCP server does not use a file-based mechanism for parameter storage. Instead, the target-resident server maintains configuration parameters in memory-resident structures. To control the contents of these memory-resident structures, you must modify the source code that defines these structures.
The following sections describe how to configure the supported DHCP server. Also included are pointers to reference information on configuring the unsupported DHCP server. If you decide to use a third-party DHCP server, consult the configuration information in the vendor-supplied documentation.
Configuring the supported (target-resident) DHCP server involves setting appropriate values for certain configuration macros. For more information on configuring VxWorks, see the Tornado User's Guide: Projects. The relevant configuration macros are those in the following list:
To determine its initial configuration data, the supported DHCP server uses the dhcpsLeaseTbl structure defined in usrNetwork.c. This structure describes the server's pool of network configuration parameter sets. It has the following format:
DHCPS_LEASE_DESC dhcpsLeaseTbl [] =
{
/* {"Name", "Start IP", "End IP", "parameters"} */
{"dflt", NULL, NULL, DHCPS_DEFAULT_ENTRY},
/* Sample database entries. */
/* {"ent1", "90.11.42.24", "90.11.42.24",
"clid=\"1:0x08003D21FE90\":maxl=90:dfl l=60"}, */
/* {"ent2", "90.11.42.25", "90.11.42.26",
"snmk=255.255.255.0:maxl=90:dfll=70:file=/vxWorks"},*/
/* {"ent3", "90.11.42.27", "90.11.42.27",
"maxl=0xffffffff:file=/vxWorks"}, */
/* {"entry4", "90.11.42.28", "90.11.42.29",
"albp=true:file=/vxWorks"} */
};
Each entry in this lease table must include an unique entry name of up to eight characters and an IP address range for assignment to requesting clients. The parameters field contains a colon-separated list of optional parameters for inclusion in the DHCP server's response. If subnetting is in effect, a critical entry in the parameters field is the subnet mask (snmk). The server does not issue addresses to clients which would change their current subnet. The address pool must specify a correct subnet mask if the default class-based mask is not valid.
A complete description of the parameters field is found in the manual pages for the DHCP server. Any parameters not specified take default values according to the Host Requirements Documents (RFC 1122 and 1123). The server can also read additional entries from an optional storage hook (discussed below).
The sample entries shown above demonstrate the possible server-issued lease types:
The lease type is used by the server to select one of the three supported mechanisms for IP address allocation. With manual allocation, DHCP simply conveys the related manual lease to the client. If dynamic allocation is used, the protocol assigns one of the dynamic leases to the client for a finite period. Automatic allocation assigns a permanent IP address from the corresponding automatic leases.
Dynamic allocation is the only method that allows reuse of addresses. The allocation type defines the priority for assigning an IP address to a DHCP client. Manual allocations have the highest priority, and automatic allocations the lowest. Among automatic leases, configurations which are available only to DHCP clients are preferred.
After the server has started, use the following routine to add new entries to the lease database:
STATUS dhcpsLeaseEntryAdd ( char * pName, /* Name of lease entry. */ char * pStartIp, /* First IP address to assign. */ char * pEndIp, /* Last IP address in assignment range. */ char * pParams /* Formatted string of lease parameters. */ )
As input, dhcpsLeaseEntryAdd( )expects to receive an entry name, starting and ending IP addresses for assignment to clients, and a formatted string containing lease parameters. If the entry is added successfully, the routine returns OK, or ERROR otherwise. This routine allows expansion of the address pool without rebuilding the VxWorks image whenever new entries are needed. If you provide an appropriate storage hook, these entries are preserved across server restarts.
To store and retrieve network configuration information, you need to implement an address storage routine and a lease storage routine. The lease storage routine uses the prototype:
STATUS dhcpsLeaseStorageHook
(
int op, /* requested storage operation */
char *pBuffer, /* memory location for record of active lease */
int dataLen /* amount of lease record data */
)
|
CAUTION: Not providing the storage routine could cause DHCP to fail.
|
||||||||||||||||||
Your lease storage routine must store and retrieve active network configurations. To install the routine you created, configure VxWorks with the DHCP Server Lease Storage Routine set to a string containing the routine name. The relevant configuration macro is DHCPS_LEASE_HOOK.
The address storage routine uses the following prototype:
STATUS dhcpsAddressStorageHook
(
int op, /* requested storage operation */
char * pName, /* name of address pool entry */
char * pStartIp, /* first IP address in range */
char * pEndIp, /* last IP address in range */
char * pParams /* lease parameters for each address */
)
Your address storage routine (optional) stores and retrieves additional address-pool entries using dhcpsLeaseEntryAdd( ). To preserve these entries, configure VxWorks with the DHCP Server Address Storage Routine set to the name of the storage routine. The relevant configuration macro is DHCPS_ADDRESS_HOOK. If this configuration is not done, active leases using alternate entries are not renewed when the server is restarted.
The cmd parameters of both storage routines expect one of the following values:2
The unsupported DHCP server is a port of a public domain server available from the WIDE project. This port modifies the original code so that it supports Solaris as well as SunOS. As a convenience, WRS provides the code for the unsupported sever in target/unsupported/dhcp-1.3beta. Unlike the supported VxWorks DHCP server, the unsupported server uses files to store the databases that track the IP addresses and the other configuration parameters that it distributes.
You can specify the names of these files in the dhcps command that you use to start the DHCP server. If you do not specify the configuration files by name, the server uses the following defaults: /etc/dhcpdb.pool, and /etc/dhcpdb.bind (or /var/db/dhcpdb.bind for BSD/OS). If the server supports a relay agent, it also maintains an extra database with the default name of /etc/dhcpdb.relay. The server also creates other files as needed in the /etc directory, but you do not need to edit these files to configure the server.
For the specifics of how you should edit these files, see the DHCPS(5), DHCPDB.POOL(5), and DHCPDB.RELAY(5) man pages included with the source code for the unsupported DHCP server.
If DHCP relay is configured into VxWorks (The relevant configuration macro is INCLUDE_DHCPR), the build generates a VxWorks image that includes the DHCP relay agent. The relay agent reads the data structure contained in usrNetwork.c to obtain the IP addresses of target DHCP servers or other relay agents. That data structure, dhcpsRelayTbl, has the following format:
DHCPS_RELAY_DESC dhcpsRelayTbl [] =
{
/* IP address of agent subnet number
------------------- ------------ */
/* {"90.11.42.254", "90.11.42.0"} */
};
Each entry in the table must specify a valid IP address for a DHCP server on a different subnet than the relay agent. The relay agent transmits a copy of all DHCP messages sent by clients to each of the specified addresses. The agent does not set the IP routing tables so that the specified target addresses are reachable.
The relay agent forwards DHCP client messages through only a limited number of targets: the DHCP Server/Relay Agent Network Radius. When the value specified in the VxWorks configuration is exceeded, the message is silently discarded. This value is only increased when the message is forwarded by a DHCP agent. It is completely independent of the similar value used by IP routers. RFC 1542 specifies the maximum value of 16 for this constant. The default hops value is four.
Beyond providing the list of target addresses, and optionally changing the maximum number of hops permitted, no further action is necessary. The DHCP relay agent executes automatically whenever it is included in the VxWorks image.
The target-resident DHCP client can retrieve multiple sets of configuration parameters. These retrieval requests can execute either synchronously or asynchronously. In addition, the retrieved network configuration information can be applied directly to the underlying network interface or used for some other purpose. The following example demonstrates the asynchronous execution of a DHCP request for a lease with a 30 minute duration in which the retrieved configuration parameters are applied to the network interface used to contact the DHCP server.3
pIf = ifunit ("net0"); /* Access network device. */
/* Initialize lease variables for automatic configuration. */
pLeaseCookie = dhcpcInit (pIf, TRUE);
if (pLeaseCookie == NULL)
return (ERROR);
/* Set any lease options here. */
dhcpcOptionSet (pLeaseCookie, _DHCP_LEASE_TIME_TAG, 1800, 0, NULL);
result = dhcpcBind (pLeaseCookie, FALSE); /* Asynchronous execution. */
if (result != OK)
return (ERROR);
In the code above, the dhcpcInit( ) call used a value of TRUE for the autoconfig parameter. This automatically includes a request for a subnet mask and broadcast address in the cookie (pLeaseCookie). To request additional options for this lease (such as a lease duration of 30 minutes) the code makes a call to dhcpcOptionSet( ). Because the DHCP protocol requires that all requested parameters be specified before a lease is established, the dhcpcOptionSet( ) call must precede the asynchronous dhcpcBind( )call that establishes the lease.
Although it is omitted from the example, you can use a dhcpcLeaseHookAdd( )call to associate a lease event hook routine with this lease. That way, you can note the DHCPC_LEASE_NEW event that occurs when the asynchronous dhcpcBind( ) completes its negotiations with the DHCP server.
To query the local DHCP client for a parameter value from the lease information it has retrieved, call dhcpcOptionGet( ). This routine checks whether the lease associated with a particular lease cookie is valid and whether the requested parameter was provided by the server. If so, dhcpcOptionGet( )copies the parameter value into a buffer. Otherwise, it returns ERROR. A call to dhcpcOptionGet( ) generates no network traffic; it queries the local DHCP client for the information it needs. The following sample demonstrates the use of this routine:
inet_addr webServer;
STATUS result;
...
result = dhcpcOptionGet (pLeaseCookie, _DHCP_DFLT_WWW_SERVER_TAG, 4,
&webServer);
if (result == OK)
printf("Primary web server: %s", inet_ntoa (webServer));
...
|
|
NOTE: To check on configuration parameters associated with a lease established at boot time, use the pDhcpcBootCookie global variable as the lease cookie in a call to dhcpcOptionGet( ).
|
||||||||||||||||||
In addition to dhcpcOptionGet( ), you can use dhcpcParamsGet( ) to retrieve multiple lease parameter values simultaneously. The DHCP client library also provides other routines that you can use to get the values of particular parameters (such as the lease timers) without supplying their option tags.
For more information on DHCP client features, see the dhcpcLib manual pages.
1: In addition to the supported target-resident server, VxWorks also includes source for an unsupported UNIX-compatible DHCP server. See target/unsupported/dhcp-1.3beta.
2: These symbolic constants are defined in dhcpsLib.h.
3: The limit on the number of concurrent leases is the "DHCP Client Maximum Leases" value set during configuration (configuration constant: DHCPC_MAX_LEASES). When setting this value, remember to count the lease (if any) that the client retrieved at boot time.