This chapter describes the protocols used for retrieving network configuration information. These protocols are:

• DHCP (Dynamic Host Configuration Protocol)

• BOOTP (Bootstrap Protocol)

• SNMP (Simple Network Management Protocol)

DHCP uses the BSD Packet Filter (BPF) in its boot scheme. For this reason, this chapter also discusses BPF.

Both a DHCP server and a BOOTP server can supply an Internet host with an IP address and related configuration information. When a BOOTP server assigns an IP address to an Internet host, the address is permanently assigned.

A DHCP server is more flexible. It assigns an IP address on either a permanent or leased basis. Leased IP addresses are an advantage in environments where large numbers of Internet hosts join the network for sessions of limited duration. Predicting the duration of such sessions is usually not possible at the time the leases are assigned.

Fortunately, a DHCP client has the ability to contact its server again and renegotiate the lease on an IP address (or request a replacement address). Unlike a BOOTP client, a DHCP client must remain active for as long as the target needs a current lease on an IP address.

Also included at the end of this section is a brief description of SNMP, an optional networking product that is compatible with VxWorks and purchased separately. For detailed usage information on SNMP, see the WindNet SNMP VxWorks Optional Product Supplement.

BOOTP is a basic bootstrap protocol implemented on top of the Internet User Datagram Protocol (UDP). The BOOTP client provided with VxWorks lets a target retrieve a single set of configuration parameters from a BOOTP server. Included among these configuration parameters is a permanently assigned IP address and a filename specifying a bootable image. To retrieve the boot file, the target can use a file transfer program, such as TFTP, FTP, or RSH.¹

Using the BOOTP server to supply boot parameters requires that you edit the server's BOOTP database file, bootptab. However, the specifics of how to do this can vary from server to server. Refer to the manuals for your host's BOOTP server. If the host does not provide a BOOTP server as part of the operating system, a copy of the publicly available CMU BOOTP server is provided in target/unsupported/bootp2.1.

The following discussion of how to modify bootptab applies to the CMU BOOTP server.

To register a VxWorks target with the BOOTP server, you must enter the target parameters in the host's BOOTP database (/etc/bootptab). The following is an example bootptab for the CMU version of the BOOTP server:

# /etc/bootptab: database for bootp server (/etc/bootpd) 
# Last update Mon 11/7/88 18:03 
# Blank lines and lines beginning with '#' are ignored. 
# 
# Legend: 
# 
#    first field -- hostname 
#             (may be full domain name and probably should be) 
# 
#    hd -- home directory 
#    bf -- boot file 
#    cs -- cookie servers 
#    ds -- domain name servers 
#    gw -- gateways 
#    ha -- hardware address 
#    ht -- hardware type 
#    im -- impress servers 
#    ip -- host IP address 
#    lg -- log servers 
#    lp -- LPR servers 
#    ns -- IEN-116 name servers 
#    rl -- resource location protocol servers 
#    sm -- subnet mask 
#    tc -- template host (points to similar host entry) 
#    to -- time offset (seconds) 
#    ts -- time servers 
# 
# Be careful to include backslashes where they are needed. Weird (bad) 
# things can happen when a backslash is omitted where one is intended. 
# 
# First, we define a global entry which specifies what every host uses. 
 
global.dummy:\ 
:sm=255.255.255.0:\ 
:hd=/usr/wind/target/vxBoot:\ 
:bf=vxWorks: 
 
vx240:ht=ethernet:ha=00DD00CB1E05:ip=150.12.1.240:tc=global.dummy 
vx241:ht=ethernet:ha=00DD00FE2D01:ip=150.12.1.241:tc=global.dummy 
vx242:ht=ethernet:ha=00DD00CB1E02:ip=150.12.1.242:tc=global.dummy 
vx243:ht=ethernet:ha=00DD00CB1E03:ip=150.12.1.243:tc=global.dummy 
vx244:ht=ethernet:ha=0000530e0018:ip=150.12.1.244:tc=global.dummy

Note that common data is described in the entry global.dummy. Any target entries that want to use the common data use tc=global.dummy. Any target-specific information is listed separately on the target line. For example, in the previous file, the entry for the target vx244 specifies only its Ethernet address (0000530e0018) and IP address (150.12.1.244). The subnet mask (255.255.255.0), home directory (/usr/wind/target/vxBoot), and boot file (VxWorks) are taken from the common entry global.dummy.

To register a target with the BOOTP server, log onto the host machine, edit the BOOTP database file to include an entry that specifies the target address (ha=), IP address (ip=), and boot file (bf=). For example, to add a target called vx245, with Ethernet address 00:00:4B:0B:B3:A8, IP address 150.12.1.245, and boot file /usr/wind/target/vxBoot/vxWorks, you would add the following line to the file:

vx245:ht=ethernet:ha=00004B0BB3A8:ip=150.12.1.245:tc=global.dummy

Note that you do not need to specify the boot filename explicitly. The home directory (hd) and the boot file (bf) are taken from global.dummy.

When performing the boot filename translation, the BOOTP server uses the value specified in the boot file field of the client request message as well as the bf (boot file) and the hd (home directory) field in the database. If the form of the filename calls for it (for example, if it is relative), the server prepends the home directory to the filename. The server checks for the existence of the file; if the file is not found, it sends no reply. For more information, see bootpd in the manual for your host.

When the server checks for the existence of the file, it also checks whether its read-access bit is set to public, because this is required by tftpd(8) to permit the file transfer. All filenames are first tried as filename.hostname and then as filename, thus providing for individual per-host boot files.

In the previous example, the server first searches for the file /usr/wind/target/vxBoot/vxWorks.vx245. If the file does not exist, the server looks for /usr/wind/target/vxBoot/vxWorks.

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 the serial reassignment of network addresses to different clients. This feature is useful when IP addresses are limited and the clients connect to the network for limited periods, such as is usually the case with clients that connect to the network over a modem.

The DHCP implementation provided with VxWorks conforms to the Internet standard RFC 2131.

The VxWorks DHCP implementation includes a server, a client, and a relay agent. You can configure your image to include all, two, one, or none of these components using the following configuration parameters:

Includes the DHCP server.

Includes the DHCPv4 run-time client. You need this code if you want the target to boot using DHCP.

Includes the DHCP relay agent. Include the DHCP relay agent if the target must relay information from a DHCP server on a different subnet.

After setting any of the above configuration parameters, rebuild VxWorks.

The following configuration parameters are set by default for the DHCP client:

Port monitored by DHCP servers. Default: 67.

Port monitored by DHCP clients. Default: 68.

Maximum number of simultaneous leases. Default: 4.

Seconds to wait for multiple offers. Default: 5.

Desired lease length in seconds. Default: 3600.

Minimum allowable lease length (seconds). Default: 30.

Maximum size (in bytes) for a DHCP message. Default: 590.
The default value is the minimum DHCP message in an Ethernet frame.

When setting values for these parameters, keep in mind that 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).

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 can add entries using dhcpLeaseEntryAdd( ), or you can 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 parameters. For more information on configuring VxWorks, see the Tornado User's Guide: Customizing VxWorks AE. The relevant configuration parameters follow:

Default: None. This constant specifies the name of the routine that handles non-volatile storage of the active leases. For more information, see Storing and Retrieving Active Network Configurations, p.106.

Default: None. This constant specifies the name of an optional storage routine. For more information, see Storing and Retrieving Active Network Configurations, p.106.

Default: 3600. This constant specifies the default lease length in seconds. This value applies if no explicit value is set in the address pool.

Default: 4. This value limits the number of subnets that a DHCP message can cross (prevents network flooding). The maximum valid value is 16.

Default: 67. This value specifies the port monitored by DHCP servers.

Default: 68. This value specifies the port monitored by DHCP clients.

Maximum size (in bytes) for a DHCP message. Default: 590.
The default value is the minimum DHCP message in an Ethernet frame.

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 the expansion of the address pool without rebuilding the 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 */ 
    )

The files in target/unsupported/dhcp-1.3beta/server contain 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.

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.

To include the VxWorks DHCP relay agent in an image, use the INCLUDE_DHCPR configuration parameter. The relay agent uses some of the same configuration parameters as the DHCP server:

Default: 4. Hops before discard, up to 16.

Default: 67. Port monitored by DHCP servers.

Default: 68. Port monitored by DHCP clients.

Maximum size (in bytes) for a DHCP message. Default: 590.

To find other DHCP relay agents or servers, the relay agent reads the dhcpTargetTbl[ ] table defined in usrNetDhcprCfg.c. This table is of the form:

DHCP_TARGET_DESC dhcpTargetTbl [] = 
    { 
    /* 
     IP address of DHCP target servers 
     --------------------------------- 
     */ 
     /* {"90.11.42.2"}, */ 
     };

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 configured value is exceeded, the message is silently discarded. This value is increased only when a DHCP agent forwards the message. 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 image.

The target-resident DHCP client can retrieve multiple sets of configuration information. 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.³

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 the code makes a call to dhcpcOptionSet( ). Because the DHCP protocol requires that all requested parameters be specified before a lease is established, both the dhcpcOptionSet( ) and dhcpcOptionAdd( ) calls 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 server provided the requested parameter. 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; 
int lenght=4; 
... 
result = dhcpcOptionGet (pLeaseCookie, _DHCP_DFLT_WWW_SERVER_TAG,  
                        &length, &webServer); 
if (result == OK) 
    printf("Primary web server: %s", inet_ntoa (webServer));  
...

Before the boot program can use a DHCP or BOOTP client to retrieve additional boot parameters from a remote server, the boot program needs appropriate values for bootDev, unitNum, procNum, and flags. See Table 5-1. Because the boot program does not yet have network access, the target must be able to find these parameter values in the default boot line, a user-provided boot line, or NVRAM boot line.⁴

If the 0x40 bit in the flags parameter is set, the boot program uses either DHCP or BOOTP client to retrieve the following parameters: ead (from which the boot program also derives a value for bad), had, gad, and bootFile.⁵ See Table 5-2.

The Simple Network Management Protocol (SNMP) lets you use a Network Management Station (NMS) to remotely configure, monitor, and manage any networked device that runs an SNMP agent. The SNMP protocol is based on an exchange of messages that set or get the value of variables in the agent's Management Information Base (MIB). Standard MIBs exist for well known protocols and network devices. By adding variables to an agent's MIB, you can accommodate new network devices and protocols as necessary.

The VxWorks stack does not bundle in SNMP support. If you need SNMP, purchase one of the following options:

• Envoy SNMP Source Code

This option provides a complete SNMP v1/v2c solution. You have the option of enhancing Envoy with Envoy+3 and Envoy+X.

• Envoy+3

This option provides SNMP v3 functionality. SNMP v3 enhances the security of the management protocol through the addition of encryption and authentication. SNMPv3 uses industry-standard protocols such as MD5 (Message Digest 5), SHA (Secure Hash Algorithm), and DES (Data Encryption Standard) to secure the communications channel. Envoy's SNMP v3 implementation also provides support for the Target and Notify MIBs.

• Envoy+X

This option provides AgentX functionality for implementing SNMP master agent/subagent systems. AgentX lets users create dynamically extensible SNMP agents. AgentX master agents communicate directly with network management stations. Subagents dynamically register with a master agent. Such functionality allows developers to design a modularly extensible system, such as a multi-blade switching chassis, that can be managed as a single device.

• WindNet SNMP

This option provides a binary version of the Envoy portable source code product.

For more information, see the Envoy Programmer's Guide and the Envoy Porting Guide.