JavaStation Client Software Guide

DHCP

This section provides a description of DHCP configuration (in files) for JavaStation clients. Complete instructions for setting up a Solaris DHCP server are provided in Chapter 4 of the TCP/IP Data Communication Administration Guide, available at http://docs.sun.com, and in the following Solaris man pages:

dhcp(4)
dhcptab(4)
in.dhcpd(1M)
dhtadm(1M)
dhcp_network(4)
dhcpconfig(1M)
pntadm(1M)

Note -

Only experienced Solaris system administrators should set up boot services for JavaStation computers using Solaris commands. Inexperienced Solaris users should use the Netra j software. For information on Netra j, go to http://www.sun.com/netra-j or refer to the Netra j 3.0 Administrator's Guide.

The DHCP server manages a pool of IP addresses for a variety of systems on the subnet, including JavaStation computers. During the boot sequence, the DHCP server delivers to the JavaStation its IP address along with other options that enable the JavaStation computer to operate on the network.

There are three types of configuration information for DHCP in the Solaris operating environment:

/etc/default/dhcp. A file that defines where the next two tables of information are stored. They can be stored either in files or in NIS+ tables.

DHCP network table. A table that maps IP addresses to all the clients on the subnet. The table is updated dynamically as IP addresses are leased and then returned to the pool. If the table is stored in a file, it is generally stored in /var/dhcp. Its name is the IP address of the (sub)net being served by the DHCP server (for example, 192_9_100_0).

DHCP service configuration table (dhcptab). A table containing the DHCP options, symbol definitions, and macros used in composing replies to clients. If this information is stored in a file, the file name is dhcptab, and it is generally stored in /var/dhcp.

The `/etc/default/dhcp` File

The /etc/default/dhcp file defines where DHCP configuration files are located. The following is a sample dhcp file.

# This file controls the defaults for datastore type and location
# for the DHCP service. Two directives are currently supported,
# RESOURCE and PATH. RESOURCE can be either "files" or "nisplus." 
# PATH can be a UNIX pathname for "files" resources, or a legal 
# NIS+ directory for "nisplus" resources.
#
RESOURCE=files
PATH=/var/dhcp

The DHCP Network Table

The DHCP network table contains a single entry for each client. Each entry contains the client identifier, the client IP address, the lease time, and other information. The DHCP server updates the network table dynamically as IP addresses are leased or relinquished by the clients.

A full description of the DHCP network table is provided in the dhcp_network(4) man page. The following is an example network table contained in a file named /var/dhcp/192_9_100_0.

# /var/dhcp/192_9_100_0
#
# Client ID|Flags|Client IP Addr|Server IP Addr|Lease Time|Macro
# 
010800208E2091 00 192.9.100.10 129.144.205.69 876425811 elvis 
010060972CF0D6 00 192.9.100.11 129.144.205.69 876432501 elvis
0108002087EC88 00 192.9.100.12 129.144.205.69 876507437 elvis
00 00 192.9.100.13 129.144.205.69 0 elvis
00 00 192.9.100.14 129.144.205.69 0 elvis

The DHCP Service Configuration Table

The DHCP Service Configuration Table contains groups of DHCP options that are delivered to DHCP clients. For a complete description of this table, refer to the dhcptab(4) man page. Throughout this section this table will be called the dhcptab file.

The DHCP options that can be delivered to JavaStation computers are a subset of all the options supported by the DHCP specification. Some DHCP options are required for a successful JavaStation boot; others are optional.

Required DHCP Options

The following table lists the DHCP options required in dhcptab to boot JavaStation computers. The left column gives the option number as defined in the DHCP specification (RFC 2132), if it exists. The middle column gives the symbol name for the option in the Solaris implementation of DHCP (the name used in dhcptab). See "Sample dhcptab File " to see how these names are used.

Table 2-3 DHCP Options Required to Boot JavaStation Computers


DHCP Option Name (Number)	Symbol Name in Solaris `dhcptab` File	Definition
N/A (This symbol is a DHCP field, not an option.)	`BootSrvA`	The IP address of the server with the initial boot file (either the booter or the JavaOS image). See Table 2-6 for more information.
IP Address Lease Time (51)	`LeaseTim`	The duration (in seconds) of the IP address lease. A value of `-1` indicates an infinite lease. After this period of time has expired without being renewed, the JavaOS software shuts down the networking port.
Subnet Mask (1)	`Subnet`	The subnet mask.
Domain Name Server (6)	`DNSserv`	The IP addresses of one or more DNS servers. The JavaOS software queries additional DNS servers if the primary server fails to respond.
DNS Domain Name (40)	`DNSdmain`	The DNS domain name.
Root Path (17)	`Rootpath`	The NFS-exported directory containing the JavaOS image. This option is used by the booter to locate the JavaOS binary and by the JavaOS software to locate a newer image to update the flash. This option is required if you are using the booter method or if flash update is enabled. See Table 2-6 for more information.

The options DHCP Message Type (53) and Server Identifier (54) are also required in every DHCP packet. However, these options are provided automatically by the DHCP server and do not need to be specified in dhcptab.

Optional DHCP Options

The following table lists the DHCP options that can be interpreted by the DHCP client during the JavaStation boot sequence but are not necessarily required for the boot sequence.

Table 2-4 Optional DHCP Options for Booting JavaStation Computers


DHCP Option Name (Number)	Symbol Name in Solaris `dhcptab` File	Definition
Bootfile Name (67)	`Bootfile`	The path name of the initial boot file, which can be a "booter" file or the JavaOS software. The path name is assumed to be relative to the TFTP root directory. If this option is not provided, the name of the booter is assumed to be the same as the Client Class Identifier (`SUNW.JDM1` for a brick model; `SUNW.JSIIep` for a tower model) and is assumed to be in the TFTP root directory. See Table 2-6 for more information.
Broadcast Address (28)	`Broadcst`	The network broadcast address.
Router (3)	`Router`	The IP address of the router to be used by the JavaStation clients. If not given, the JavaOS software uses router discovery to locate a router.
Time Server (4)	`Timeserv`	The IP address of a server supporting the RFC 868 time protocol.
N/A (Solaris-specific flag)	`LeaseNeg`	A boolean flag which by its presence tells the DHCP server to renew the leases of clients requesting IP address lease renewal.
NIS Servers (41)	`NISservs`	If the IP address of an NIS server is not given, the JavaOS software broadcasts looking for NIS servers. (This works only if the NIS server is on the same subnet.)
NIS Domain Name (40)	`NISdmain`	The NIS domain name.
Vendor-Specific Options (43)	Symbol names are defined by the user. By convention, use `JOScmd1` through `JOScmd4`, `JOSchksm`, and `JSBproto`	A list of vendor-specific options. See "Vendor-Specific Options".

See "Sample dhcptab File " for examples of how these options are set in dhcptab.

Vendor-Specific Options

The DHCP specification enables hardware and software vendors to create their own DHCP options. These options are delivered through the use of the Client Class Identifier option and the Vendor-Specific Options option. If a DHCP client identifies itself as being of a certain class of client, and the DHCP server has been configured to serve that class of clients, then the DHCP server can respond with a set of options specific to that client type.

Vendor-Specific Options can be used to deliver the JavaOS checksum, JavaOS property settings, and the JavaOS boot protocol to the JavaStation computer during the boot sequence.

The checksum identifies the JavaOS image that is available from a network server and helps determine whether that image is updated in JavaStation flash memory, as described in "Task 4: Update Flash Memory With New JavaOS Image ". Also see "Managing the JavaOS Checksum".

JavaOS property settings determine the resources the JavaOS software uses and other JavaOS attributes. For information on JavaOS properties, see Chapter 4, JavaOS Properties .

The JavaOS boot protocol is the protocol used to download JavaOS from a network server to the JavaStation computer. Possible settings for the boot protocol are tftp and nfs.

The delivery of Vendor-Specific Options to JavaStation clients works as follows. The DHCP client on the JavaStation (the PROM or the JavaOS software) includes the JavaStation hardware's Client Class Identifier (DHCP Option #60) in every packet sent to the DHCP server. When the DHCP server receives the Client Class Identifier, it will deliver the JavaOS checksum, boot protocol, and/or property settings in the Vendor-Specific Options if it has been configured to do so.

The JavaStation hardware's Client Class Identifier is specified in the PROM. The table below lists the Client Class Identifiers for each JavaStation model.

Table 2-5 JavaStation Client Class Identifiers


JavaStation Model	Client Class Identifier
Brick model	`SUNW.JDM1`
Tower model	`SUNW.JSIIep`

Examine the sample dhcptab file below for examples of setting the JavaOS checksum and JavaOS properties in dhcptab. Note, however, that JavaOS properties can be delivered to the JavaOS software using methods other than the DHCP Vendor-Specific Options. See Chapter 4, JavaOS Properties for more information.

Sample `dhcptab` File

The following sample dhcptab file supplies DHCP options to a variety of clients on a network. Some options are common to all clients. Other options are specific to clients attached to the server, to classes of JavaStation clients, or to specific JavaStation machines. Note that dhcptab can serve many different clients, not just JavaStation computers.

# /var/dhcp/dhcptab
#
# This file is a sample DHCP server configuration database for 
# JavaStation clients.
#
# Refer to dhcptab(4) for details. This table is generated by
# using the dhcpconfig(1M) command in conjunction with the
# dhtadm(1M) command. It can be administered with the dhtadm
# command.

# The following are symbol definitions for the Vendor-Specific 
# Options. Symbol definitions are used to create dhcptab macros.
# Refer to the dhcptab(4) man page for symbol definition syntax and
# instructions on creating macros. 

# JOScmd1-4 are for JavaOS properties, JOSchksm is for the 
# JavaOS checksum, and JSBproto is for the JavaOS boot protocol. 

JOScmd1				s		Vendor=SUNW.JSIIep SUNW.JDM1,101,ASCII,1,0
JOScmd2				s 		Vendor=SUNW.JSIIep SUNW.JDM1,102,ASCII,1,0
JOScmd3				s 		Vendor=SUNW.JSIIep SUNW.JDM1,103,ASCII,1,0
JOScmd4				s 		Vendor=SUNW.JSIIep SUNW.JDM1,104,ASCII,1,0

JOSchksm 				s 		Vendor=SUNW.JSIIep,128,NUMBER,4,1

JSBproto				s		Vendor=SUNW.JSIIep,129,ASCII,1,0

# Standard macros generated when configured with dhcpconfig(1M). # The first is the time offset from GMT (UTC) time, the second
# applies to all clients serviced by this server, and the third
# applies to all clients attached to one of the nets attached to
# the server.

Locale			m 	:UTCoffst=-25200:

gibson			m 	:Include=Locale:Timeserv=10.146.103.191:\
				:LeaseTim=259200:LeaseNeg:\
				:DNSserv=10.146.1.151 10.146.1.152 10.144.1.57:\
				:DNSdmain=foo.bar.com:
10.146.103.0						m 		:Broadcst=10.146.103.255:\
								:Subnet=255.255.255.0:\
								:MTU=1500:Router=10.146.103.1:\
								:NISdmain=nis.foo.bar.com:\
								:NISservs=10.146.103.22:\
								:BootSrvA=10.146.103.191:

# These are macros used to configure specific classes of clients. 
# In this case the JavaStation tower and brick models respectively.

SUNW.JSIIep						m 		:Rootpath="/export/root/javaos/JSIIep":\
								:JOScmd1="-ihttp://gibson:8080/properties":\
								:JOSchksm=0x13d624be:

SUNW.JDM1				m 			:Rootpath="/export/root/javaos/JDM1":\
							:JOScmd1="-ihttp://gibson:8080/properties.JDM1":

# The macros below contain individual DHCP options for the two
# JavaStation computers whose client ID's (derived from the
# Ethernet address) match the keys. Here each JavaStation gets 
# its boot image from a boot server other than the DHCP server. 
# The first JavaStation uses NFS to directly download the 
# JavaOS image. The second JavaStation computer gets a different
# properties file as well as empty vendor options that override
# any previous default definitions.

0800208E0668						m 			:BootSrvA=10.146.103.11:\
									:JOSchksm=0x13b74098:JSBproto="nfs":

08002087BED4						m 			:BootSrvA=10.146.103.114:\
									:JOScmd1="-ihttp://redwings/properties":\
									:JOScmd2="":JOScmd3="":JOScmd4="":\
									:JOSchksm=0x13dd4e2d:

Managing the JavaOS Checksum

Each time you receive a new copy of the JavaOS software, you can configure the DHCP server to deliver the new copy to JavaStation computers by following the first set of instructions below. To disable JavaOS updating on the JavaStation computers, follow the second set of instructions.

To Configure the DHCP Server for a New JavaOS Binary

Determine the checksum.

The checksum is contained in the first 4 bytes of the last 12 bytes of the JavaOS binary file.
```
% tail -12c  javaos | od -X | nawk '{print "0x" $2}'
14eb02a1 
```

Use dhtadm to add the new checksum to the DHCP configuration.
```
% dhtadm -M -m SUNW.JSIIep -e JOSchksm=0xchecksum 
```

For example,

% dhtadm -M -m SUNW.JSIIep -e JOSchksm=0x14eb02a1

When each JavaStation computer boots, its flash memory is updated with the new JavaOS binary and then is rebooted using the new JavaOS binary. This action may be automatic or require user confirmation, depending on other options.

To Disable JavaOS Updating

Set the checksum to zero:

% dhtadm -M -m SUNW.JSIIep -e JOSchksm=0

Delete the checksum entirely from the DHCP configuration:
```
% dhtadm -M -m SUNW.JSIIep -e JOSchksm= 
```

Note that there is nothing after the equal sign.