dhcpsLib

NAME

dhcpsLib - Dynamic Host Configuration Protocol (DHCP) server library

ROUTINES

dhcpsInit( ) - set up the DHCP server parameters and data structures
dhcpsLeaseEntryAdd( ) - add another entry to the address pool
dhcpsLeaseHookAdd( ) - assign a permanent lease storage hook for the server
dhcpsAddressHookAdd( ) - assign a permanent address storage hook for the server

DESCRIPTION

This library implements the server side of the Dynamic Host Configuration Protocol (DHCP). DHCP is an extension of BOOTP. Like BOOTP, it allows a target to configure itself dynamically by using the network to get its IP address, a boot file name, and the DHCP server's address. Additionally, DHCP provides for automatic reuse of network addresses by specifying individual leases as well as many additional options. The compatible message format allows DHCP participants to interoperate with BOOTP participants. The dhcpsInit( ) routine links this library into the VxWorks image. This happens automatically if INCLUDE_DHCPS is defined when the image is built.

PRIMARY INTERFACE

The dhcpsInit( ) routine initializes the server. It reads the hard-coded server configuration data that is stored in three separate tables. The first table contains entries as follows:
DHCPS_LEASE_DESC dhcpsLeaseTbl [] =
    {
    {"sample1", "90.11.42.24", "90.11.42.24", "clid=\"1:0x08003D21FE90\""},
    {"sample2", "90.11.42.25", "90.11.42.28", "maxl=90:dfll=60"},
    {"sample3", "90.11.42.29", "90.11.42.34", "maxl=0xffffffff:file=/vxWorks"},
    {"sample4", "90.11.42.24", "90.11.42.24", "albp=true:file=/vxWorks"}
    };
Each entry contains a name of up to eight characters, the starting and ending IP addresses of a range, and the parameters associated with the lease. The four samples shown demonstrate the four types of leases.
Manual leases contain a specific client ID, and are issued only to that client, with an infinite duration. The example shown specifies a MAC address, which is the identifier type used by the VxWorks DHCP client.
Dynamic leases specify a finite maximum length, and can be issued to any requesting client. These leases allow later re-use of the assigned IP address. If not explicitly specified in the parameters field, these leases use the values of DHCPS_MAX_LEASE and DHCPS_DFLT_LEASE to determine the lease length.
Automatic leases are implied by the infinite maximum length. Their IP addresses are assigned permanently to any requesting client.
The last sample demonstrates a lease that is also available to BOOTP clients. The infinite maximum length is implied, and any timing-related parameters are ignored.
The DHCP server supplies leases to DHCP clients according to the lease type in the order shown above. Manual leases have the highest priority and leases available to BOOTP clients the lowest.
Entries in the parameters field may be one of these types:

bool
Takes values of "true" or "false", for example, ipfd=true. Unrecognized values default to false.

str
Takes a character string as a value, for example, hstn="clapton". If the string includes a delimiter character, such as a colon, it should be enclosed in quotation marks.

octet
Takes an 8-bit integer in decimal, octal, or hexadecimal, for example, 8, 070, 0xff.

short
Takes a 16-bit integer.

long
Takes a 32-bit integer.

ip
Takes a string that is interpreted as a 32-bit IP address. One of the following formats is expected: a.b.c.d, a.b.c or a.b. In the second format, c is interpreted as a 16-bit value. In the third format, b is interpreted as a 24-bit value, for example siad=90.11.42.1.

iplist
Takes a list of IP addresses, separated by white space, for example, rout=133.4.31.1 133.4.31.2 133.4.31.3.

ippairs
Takes a list of IP address pairs. Each IP address is separated by white space and grouped in pairs, for example, strt=133.4.27.0 133.4.31.1 133.4.36.0 133.4.31.1.

mtpt
Takes a list of 16 bit integers, separated by white space, for example, mtpt=1 2 3 4 6 8.

clid
Takes a client identifier as a value. Client identifiers are represented by the quoted string "type:data", where type is an integer from 0 to 255, as defined by the IANA, and data is a sequence of 8-bit values in hexadecimal. The client ID is usually a MAC address, for example, clid="1:0x08004600e5d5".

The following table lists the option specifiers and descriptions for every possible entry in the parameter list. When available, the option code from RFC 2132 is included.

Name Code Type Description

snam - str Optional server name.

file - str Name of file containing the boot image.

siad - ip Address of server that offers the boot image.

albp - bool If true, this entry is also available

to BOOTP clients. For entries using

static allocation, this value becomes

true by default and maxl becomes

infinity.

maxl - long Maximum lease duration in seconds.

dfll - long Default lease duration in seconds. If a

client does not request a specific lease

duration, the server uses this value.

clid - clid This specifies a client identifier for

manual leases. The VxWorks client uses

a MAC address as the client identifier.

pmid - clid This specifies a client identifier for

client-specific parameters to be included

in a lease. It should be present in separate

entries without IP addresses.

clas - str This specifies a class identifier for

class-specific parameters to be included in

a lease. It should be present in separate entries

without IP addresses.

snmk 1 ip Subnet mask of the IP address to be

allocated. The default is a natural mask

corresponding to the IP address. The

server will not issue IP addresses to

clients on different subnets.

tmof 2 long Time offset from UTC in seconds.

rout 3 iplist A list of routers on the same subnet as

the client.

tmsv 4 iplist A list of time servers (RFC 868).

nmsv 5 iplist A list of name servers (IEN 116).

dnsv 6 iplist A list of DNS servers (RFC 1035).

lgsv 7 iplist A list of MIT-LCS UDP log servers.

cksv 8 iplist A list of Cookie servers (RFC 865).

lpsv 9 iplist A list of LPR servers (RFC 1179).

imsv 10 iplist A list of Imagen Impress servers.

rlsv 11 iplist A list of Resource Location servers (RFC 887).

hstn 12 str Hostname of the client.

btsz 13 short Size of boot image.

mdmp 14 str Path name to which client dumps core.

dnsd 15 str Domain name for DNS.

swsv 16 ip IP address of swap server.

rpth 17 str Path name of root disk of the client.

epth 18 str Extensions Path (See RFC 1533).

ipfd 19 bool If true, the client performs IP

forwarding.

nlsr 20 bool If true, the client can perform non-local

source routing.

plcy 21 ippairs Policy filter for non-local source

routing. A list of pairs of

(Destination IP, Subnet mask).

mdgs 22 short Maximum size of IP datagram that the

client should be able to reassemble.

ditl 23 octet Default IP TTL.

mtat 24 long Aging timeout (in seconds) to be used

with Path MTU discovery (RFC 1191).

mtpt 25 mtpt A table of MTU sizes to be used with

Path MTU Discovery.

ifmt 26 short MTU to be used on an interface.

asnl 27 bool If true, the client assumes that all

subnets to which the client is connected

use the same MTU.

brda 28 ip Broadcast address in use on the client's

subnet. The default is calculated from

the subnet mask and the IP address.

mskd 29 bool If true, the client should perform subnet

mask discovery using ICMP.

msks 30 bool If true, the client should respond to

subnet mask requests using ICMP.

rtrd 31 bool If true, the client should solicit

routers using Router Discovery defined

in RFC 1256.

rtsl 32 ip Destination IP address to which the

client sends router solicitation

requests.

strt 33 ippairs A table of static routes for the client,

which are pairs of (Destination, Router).

It is illegal to specify default route

as a destination.

trlr 34 bool If true, the client should negotiate

the use of trailers with ARP (RFC 893).

arpt 35 long Timeout in seconds for ARP cache.

encp 36 bool If false, the client uses RFC 894

encapsulation. If true, it uses

RFC 1042 (IEEE 802.3) encapsulation.

dttl 37 octet Default TTL of TCP.

kain 38 long Interval of the client's TCP keepalive

in seconds.

kagb 39 bool If true, the client should send TCP

keepalive messages with a octet of

garbage for compatibility.

nisd 40 str Domain name for NIS.

nisv 41 iplist A list of NIS servers.

ntsv 42 iplist A list of NTP servers.

nnsv 44 iplist A list of NetBIOS name server.

(RFC 1001, 1002)

ndsv 45 iplist A list of NetBIOS datagram distribution

servers (RFC 1001, 1002).

nbnt 46 octet NetBIOS node type (RFC 1001, 1002).

nbsc 47 str NetBIOS scope (RFC 1001, 1002).

xfsv 48 iplist A list of font servers of X Window system.

xdmn 49 iplist A list of display managers of X Window

system.

dht1 58 short This value specifies when the client should

start RENEWING. The default of 500 means

the client starts RENEWING after 50% of the

lease duration passes.

dht1 59 short This value specifies when the client should

start REBINDING. The default of 875 means

the client starts REBINDING after 87.5% of

the lease duration passes.

Finally, to function correctly, the DHCP server requires access to some form of permanent storage. The DHCPS_LEASE_HOOK constant specifies the name of a storage routine with the following interface:
    STATUS dhcpsStorageHook (int op, char *buffer, int datalen);
The storage routine is installed by a call to the dhcpsLeaseHookAdd( ) routine The manual pages for dhcpsLeaseHookAdd( ) describe the parameters and required operation of the storage routine.

Name	Code	Type	Description

snam	-	str	Optional server name.

file	-	str	Name of file containing the boot image.

siad	-	ip	Address of server that offers the boot image.

albp	-	bool	If true, this entry is also available
			to BOOTP clients. For entries using
			static allocation, this value becomes
			true by default and maxl becomes
			infinity.

maxl	-	long	Maximum lease duration in seconds.

dfll	-	long	Default lease duration in seconds. If a
			client does not request a specific lease
			duration, the server uses this value.

clid	-	clid	This specifies a client identifier for
			manual leases. The VxWorks client uses
			a MAC address as the client identifier.

pmid	-	clid	This specifies a client identifier for
			client-specific parameters to be included
			in a lease. It should be present in separate
			entries without IP addresses.

clas	-	str	This specifies a class identifier for
			class-specific parameters to be included in
			a lease. It should be present in separate entries
			without IP addresses.

snmk	1	ip	Subnet mask of the IP address to be
			allocated. The default is a natural mask
			corresponding to the IP address. The
			server will not issue IP addresses to
			clients on different subnets.

tmof	2	long	Time offset from UTC in seconds.

rout	3	iplist	A list of routers on the same subnet as
			the client.

tmsv	4	iplist	A list of time servers (RFC 868).

nmsv	5	iplist	A list of name servers (IEN 116).

dnsv	6	iplist	A list of DNS servers (RFC 1035).

lgsv	7	iplist	A list of MIT-LCS UDP log servers.

cksv	8	iplist	A list of Cookie servers (RFC 865).

lpsv	9	iplist	A list of LPR servers (RFC 1179).

imsv	10	iplist	A list of Imagen Impress servers.

rlsv	11	iplist	A list of Resource Location servers (RFC 887).

hstn	12	str	Hostname of the client.

btsz	13	short	Size of boot image.

mdmp	14	str	Path name to which client dumps core.

dnsd	15	str	Domain name for DNS.

swsv	16	ip	IP address of swap server.

rpth	17	str	Path name of root disk of the client.

epth	18	str	Extensions Path (See RFC 1533).

ipfd	19	bool	If true, the client performs IP
			forwarding.

nlsr	20	bool	If true, the client can perform non-local
			source routing.

plcy	21	ippairs	Policy filter for non-local source
			routing. A list of pairs of
			(Destination IP, Subnet mask).

mdgs	22	short	Maximum size of IP datagram that the
			client should be able to reassemble.

ditl	23	octet	Default IP TTL.

mtat	24	long	Aging timeout (in seconds) to be used
			with Path MTU discovery (RFC 1191).

mtpt	25	mtpt	A table of MTU sizes to be used with
			Path MTU Discovery.

ifmt	26	short	MTU to be used on an interface.

asnl	27	bool	If true, the client assumes that all
			subnets to which the client is connected
			use the same MTU.

brda	28	ip	Broadcast address in use on the client's
			subnet. The default is calculated from
			the subnet mask and the IP address.

mskd	29	bool	If true, the client should perform subnet
			mask discovery using ICMP.

msks	30	bool	If true, the client should respond to
			subnet mask requests using ICMP.

rtrd	31	bool	If true, the client should solicit
			routers using Router Discovery defined
			in RFC 1256.

rtsl	32	ip	Destination IP address to which the
			client sends router solicitation
			requests.

strt	33	ippairs	A table of static routes for the client,
			which are pairs of (Destination, Router).
			It is illegal to specify default route
			as a destination.

trlr	34	bool	If true, the client should negotiate
			the use of trailers with ARP (RFC 893).

arpt	35	long	Timeout in seconds for ARP cache.

encp	36	bool	If false, the client uses RFC 894
			encapsulation. If true, it uses
			RFC 1042 (IEEE 802.3) encapsulation.

dttl	37	octet	Default TTL of TCP.

kain	38	long	Interval of the client's TCP keepalive
			in seconds.

kagb	39	bool	If true, the client should send TCP
			keepalive messages with a octet of
			garbage for compatibility.

nisd	40	str	Domain name for NIS.

nisv	41	iplist	A list of NIS servers.

ntsv	42	iplist	A list of NTP servers.

nnsv	44	iplist	A list of NetBIOS name server.
			(RFC 1001, 1002)

ndsv	45	iplist	A list of NetBIOS datagram distribution
			servers (RFC 1001, 1002).

nbnt	46	octet	NetBIOS node type (RFC 1001, 1002).

nbsc	47	str	NetBIOS scope (RFC 1001, 1002).

xfsv	48	iplist	A list of font servers of X Window system.

xdmn	49	iplist	A list of display managers of X Window
			system.

dht1	58	short	This value specifies when the client should
			start RENEWING. The default of 500 means
			the client starts RENEWING after 50% of the
			lease duration passes.

dht1	59	short	This value specifies when the client should
			start REBINDING. The default of 875 means
			the client starts REBINDING after 87.5% of
			the lease duration passes.

SECONDARY INTERFACE

In addition to the hard-coded entries, address entries may be added after the server has started by calling the following routine:
    STATUS dhcpsLeaseEntryAdd (char *name, char *start, char *end, char *config);
The parameters specify an entry name, starting and ending values for a block of IP addresses, and additional configuration information in the same format as shown above for the hard-coded entries. Each parameter must be formatted as a NULL-terminated string.
The DHCPS_ADDRESS_HOOK constant specifies the name of a storage routine, used to preserve address entries added after startup, which has the following prototype:
    STATUS dhcpsAddressStorageHook (int op,
                                    char *name, char *start, char *end, 
                                    char *params);
The storage routine is installed with the dhcpsAddressHookAdd( ) routine, and is fully described in the manual pages for that function.

OPTIONAL INTERFACE

The DHCP server can also receive messages forwarded from different subnets by a relay agent. To provide addresses to clients on different subnets, the appropriate relay agents must be listed in the provided table in usrNetwork.c. A sample configuration is:
    DHCPS_RELAY_DESC dhcpsRelayTbl [] =
        {
        {"90.11.46.75", "90.11.46.0"}
        };
Each entry in the table specifies the address of a relay agent that will transmit the request and the corresponding subnet number. To issue leases successfully, the address pool must also contain IP addresses for the monitored subnets.
The following table allows a DHCP server to act as a relay agent in addition to its default function of processing messages. It consists of a list of IP addresses.
    DHCP_TARGET_DESC dhcpTargetTbl [] =
         {
         {"90.11.43.2"},
         {"90.11.44.1"}
         };
Each IP address in this list receives a copy of any client messages generated on the subnets monitored by the server.

INCLUDE FILES

dhcpsLib.h

dhcpsInit( )

NAME

dhcpsInit( ) - set up the DHCP server parameters and data structures

SYNOPSIS

STATUS dhcpsInit
    (
    struct ifnet * *   ppIf,       /* network devices used by server */
    int                numDev,     /* number of devices */
    int                maxSize,    /* largest DHCP message supported */
    DHCPS_LEASE_DESC * pLeasePool, /* table of lease data */
    int                poolSize,   /* size of data table */
    DHCPS_RELAY_DESC * pRelayTbl,  /* table of relay agent data */
    int                relaySize,  /* size of relay agent table */
    DHCP_TARGET_DESC * pTargetTbl, /* table of receiving DHCP servers */
    int                targetSize
    )

DESCRIPTION

This routine creates the necessary data structures, builds the server address pool, retrieves any lease or address information from permanent storage through the user-provided hooks, and initializes the network interfaces for monitoring. It is called at system startup if INCLUDE_DHCPS is defined at the time the VxWorks image is built.
The maxSize parameter specifies the maximum length supported for any DHCP message, including the UDP and IP headers and the largest link level header for all supported devices. The smallest valid value is 576 bytes, corresponding to the minimum IP datagram a host must accept. Larger values will allow the server to handle longer DHCP messages.

RETURNS

OK, or ERROR if could not initialize.

dhcpsLeaseEntryAdd( )

NAME

dhcpsLeaseEntryAdd( ) - add another entry to the address pool

SYNOPSIS

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 */
    )

DESCRIPTION

This routine allows the user to add new entries to the address pool without rebuilding the VxWorks image. The routine requires a unique entry name of up to eight characters, starting and ending IP addresses, and a colon-separated list of parameters. Possible values for the parameters are listed in the reference entry for dhcpsLib. The parameters also determine the type of lease, which the server uses to determine priority when assigning lease addresses. For examples of the possible lease types, see the reference entry for dhcpsLib.

RETURNS

OK if entry read successfully, or ERROR otherwise.

ERRNO

N/A

dhcpsLeaseHookAdd( )

NAME

dhcpsLeaseHookAdd( ) - assign a permanent lease storage hook for the server

SYNOPSIS

STATUS dhcpsLeaseHookAdd
    (
    FUNCPTR pCacheHookRtn /* routine to store/retrieve lease records */
    )

DESCRIPTION

This routine allows the server to access some form of permanent storage that it can use to store current lease information across restarts. The only argument to dhcpsLeaseHookAdd( ) is a pointer to a storage routine with the following interface:
    STATUS dhcpsStorageHook (int op, char *buffer, int datalen);
The first parameter of the storage routine specifies one of the following operations:
    DHCPS_STORAGE_START
    DHCPS_STORAGE_READ
    DHCPS_STORAGE_WRITE
    DHCPS_STORAGE_STOP
    DHCPS_STORAGE_CLEAR
In response to START, the storage routine should prepare to return data or overwrite data provided by earlier WRITEs. For a WRITE the storage routine must save the contents of the buffer to permanent storage. For a READ, the storage routine should copy data previously stored into the provided buffer as a NULL-terminated string in FIFO order. For a CLEAR, the storage routine should discard currently stored data. After a CLEAR, the READ operation must return ERROR until additional data is stored. For a STOP, the storage routine must handle cleanup. After a STOP, READ and WRITE operations must return error until a START is received. Each of these operations must return OK if successful, or ERROR otherwise.
Before the server is initialized, VxWorks automatically calls dhcpsLeaseHookAdd( ), passing in the routine name defined by DHCPS_LEASE_HOOK.

RETURNS

OK, or ERROR if routine is NULL.

ERRNO

N/A

dhcpsAddressHookAdd( )

NAME

dhcpsAddressHookAdd( ) - assign a permanent address storage hook for the server

SYNOPSIS

STATUS dhcpsAddressHookAdd
    (
    FUNCPTR pCacheHookRtn /* routine to store/retrieve lease entries */
    )

DESCRIPTION

This routine allows the server to access some form of permanent storage to preserve additional address entries across restarts. This routine is not required, but leases using unsaved addresses are not renewed. The only argument provided is the name of a function with the following interface:
    STATUS dhcpsAddressStorageHook (int op,
                                    char *name, char *start, char *end, 
                                    char *params);
The first parameter of this storage routine specifies one of the following operations:
    DHCPS_STORAGE_START
    DHCPS_STORAGE_READ
    DHCPS_STORAGE_WRITE
    DHCPS_STORAGE_STOP
In response to a START, the storage routine should prepare to return data or overwrite data provided by earlier WRITE operations. For a WRITE, the storage routine must save the contents of the four buffers to permanent storage. Those buffers contain the NULL-terminated strings received by the dhcpsLeaseEntryAdd( ) routine. For a READ, the storage routine should copy previously stored data (as NULL-terminated strings) into the provided buffers in the order received by earlier WRITE operations. For a STOP, the storage routine should do any necessary cleanup. After a STOP, the storage routine should return an ERROR for all operations except START. However, the STOP operation does not normally occur since the server only deliberately exits following an unrecoverable error. This storage routine must not rely on that operation to handle READ, WRITE, or new START attempts.
The storage routine should return OK if successful, ERROR otherwise.
Note that, unlike the lease storage routine, there is no CLEAR operation.
Before the server is initialized, VxWorks calls this routine automatically passing in the function named in DHCPS_ADDRESS_HOOK.

RETURNS

OK, or ERROR if function pointer is NULL.

ERRNO

N/A

dhcpsLib

NAME

ROUTINES

DESCRIPTION

PRIMARY INTERFACE

SECONDARY INTERFACE

OPTIONAL INTERFACE

INCLUDE FILES

SEE ALSO

dhcpsInit( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

dhcpsLeaseEntryAdd( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

dhcpsLeaseHookAdd( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

dhcpsAddressHookAdd( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO