VxWorks Reference Manual : Libraries

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 in usrNetwork.c. 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 1533 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.

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

SEE ALSO

dhcpsLib, RFC 1541, RFC 1533


Libraries : Routines

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

RETURNS

OK, or ERROR if could not initialize.

SEE ALSO

dhcpsLib


Libraries : Routines

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

SEE ALSO

dhcpsLib


Libraries : Routines

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, calls to the storage routine 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

SEE ALSO

dhcpsLib


Libraries : Routines

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.

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

SEE ALSO

dhcpsLib