Netra j 2.0 Administrator's Guide

Chapter 8 Booting the JavaStation Using Solaris

This chapter describes the JavaStation boot sequence and explains how to set up JavaStation boot services in the Solaris operating environment.

JavaStation Boot Sequence

The JavaStation boot sequence uses the following network services:

These services do not have to reside on the same machine. As mentioned in Chapter 2, Booting the JavaStation Using Netra j, NIS and DNS services must also be provided on the network for JavaStation computers to operate correctly, but they are not directly involved in the boot sequence.

The boot sequence can occur in a variety of ways. Essentially, it must accomplish the following tasks:

  1. Lease an IP address to the JavaStation computer. Each JavaStation must lease an IP address from an address pool managed by a DHCP server. It is recommended that the DHCP server assign addresses dynamically. However, the Solaris DHCP server can also be set up with statically assigned IP addresses.

  2. Deliver and boot JavaOS on the JavaStation computer. JavaOS can be delivered to the JavaStation computers from a network server via TFTP or TFTP and NFS. Alternatively, if the JavaStation has flash memory, JavaOS can be booted from flash.

  3. Deliver the main user application to the JavaStation computer. The main user application can be delivered to the JavaStation computers via HTTP. Alternatively, JavaOS and the main application can be compiled together into a single boot image.

  4. Update the JavaOS stored in flash memory. This task applies only to JavaStation clients with flash memory (available only on "tower" models). After the JavaStation boots, the JavaOS file stored in flash memory can be updated if a newer copy of JavaOS exists on the network. If the flash memory is updated, the JavaStation immediately reboots with the newer copy of JavaOS.

The following sections describe the JavaStation power-on and boot sequence tasks in detail.

Power-On

The JavaStation programmable read-only memory (PROM) includes TFTP client and DHCP client implementations and is thus able to carry out the boot sequence. At power-on, the PROM checks to see if flash memory is present. If so, it then checks to make sure the JavaOS in flash is not corrupted. If the JavaOS in flash is valid, then the PROM loads it into memory and transfers control to it. JavaOS initializes itself and then completes Task 1, described below.

If any of the above tests fail, JavaOS is not loaded into memory and the PROM proceeds to complete Task 1 itself.

Task 1: Lease an IP Address

Either the PROM or JavaOS leases an IP address from the DHCP server by completing the following handshake with the JavaStation DHCP server. For simplicity, the description below refers to the PROM or JavaOS as "the DHCP client."

  1. The DHCP client broadcasts DHCPDISCOVER packets at intervals until a DHCPOFFER is received. The DHCPDISCOVER packet includes the Client Class Identifier option, which identifies the DHCP client as being a JavaStation (see "Vendor-Specific Options"). During this broadcast, a notice is displayed on the JavaStation screen approximately every minute so the user knows if the server is not responding.

  2. One or more DHCP servers respond with DHCPOFFER packets. The DHCPOFFER(s) are examined by the DHCP client to determine whether they contain the options required to boot JavaStation computers (see "DHCP").

  3. The DHCP client chooses the first OFFER it receives that contains the required options. The DHCP client remembers the IP address of the server that sent the OFFER.

  4. The DHCP client broadcasts a DHCPREQUEST packet. This packet contains the IP address of the server chosen in the previous step. All other DHCP servers that responded in the second step are thus informed that they have not been selected.

  5. The selected server sends a DHCPACK packet back to the DHCP client.

At this point, the JavaStation has received all of its configuration information from the DHCP server. Figure 8-1 illustrates the initial handshake.

Figure 8-1 JavaStation Client - DHCP Server Handshake

Graphic

Task 2: Deliver and Boot JavaOS

Task 2 is to pass control of the JavaStation to JavaOS. If JavaOS has not been loaded from flash memory, Task 2 is performed using a method determined by information delivered by the DHCP server in the initial handshake. Table 8-1 shows JavaOS boot information from the DHCP server and the resulting actions taken by the JavaStation PROM.

Table 8-1 DHCP Information for Booting JavaOS

If the DHCP server delivers... 

JavaOS is downloaded and booted as follows  

The IP address of a server that has an initial boot program (the "booter") in its TFTP root directory  

The JavaStation PROM downloads the booter from the server using TFTP, then transfers control to it.  

When the booter begins execution, it scans the PROM's device tree for the name and location of the JavaOS image and the name of a server that contains this image in an NFS-exported directory. If the booter does not find this information in the PROM, it obtains it from the DHCP server. The booter mounts this directory, copies the JavaOS image, and transfers control to it.  

The IP address of a server that has JavaOS in its TFTP root directory 

The JavaStation PROM downloads JavaOS from the server using TFTP, then transfers control to it. (Note that this is the slower of the two options.)  

The DHCP server delivers information in the DHCP options, which are described on "The DHCP Service Configuration Table ". For instructions on setting the options used to deliver the above information, see Table 8-6.

Task 3: Deliver Main Application

The main application can be compiled with JavaOS into a single executable that is stored in flash or delivered to the JavaStation using either method described in the table above.

Alternatively, the main application is delivered to the JavaStation by a web server (HTTP server) on the network. The URL of the application zip file and other JavaOS application loading properties are passed to the DHCP client in the initial handshake through the DHCP Vendor-Specific Options, described on "Vendor-Specific Options". For descriptions of the JavaOS application loading properties, see "Application Loading Properties".

Task 4: Update Flash Memory with New JavaOS

Tower model JavaStation computers include flash memory to store the JavaOS binary file. After JavaOS finishes its initialization, it determines whether it needs to update the flash memory with a new JavaOS based on the following criteria:

Both the property and the checksum are delivered by DHCP as Vendor-Specific Options. See "Vendor-Specific Options".

The JavaOS checksum identifies the revision level of the JavaOS binary file. It is contained in the first four bytes of the last 12 bytes of the file. For more information, see "Managing the JavaOS Checksum".

The results of each possible set of conditions are shown in Table 8-2.

Table 8-2 Conditions for Updating JavaStation Flash Memory

Conditions 

Results  

javaos.alwaysUpdate 

Checksum 

 

not set  

different  

JavaOS opens a Flash Update dialog box on the JavaStation screen. You have the option of updating flash memory with the new copy of JavaOS. 

not set  

same  

JavaOS does not update the flash memory.  

true

different  

JavaOS updates flash memory without querying the user.  

true

same 

JavaOS does not update the flash memory.  

false

different  

JavaOS does not update the flash memory.  

false

same  

JavaOS does not update the flash memory.  

If the flash memory is updated, the JavaStation immediately reboots with the new copy of JavaOS.

Note that if any of the following conditions exist, flash memory is never updated:

Setting Up Boot Services

This section describes how to set up DHCP, TFTP, NFS, and HTTP services to administer JavaStation computers on your network.

DHCP

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 to operate on the network.

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

Solaris DHCP configuration information is managed using the following command line utilities:

This section provides guidelines for setting up DHCP configuration information (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:

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 the file /var/dhcp/192_9_100_0.


# /var/dhcp/192_9_100_0
#
# Client ID[boxv  ]Flags[boxv  ]Client IP Addr[boxv  ]Server IP Addr[boxv  ]Lease Time[boxv  ]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 will be 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

Table 8-3 lists the DHCP options required in dhcptab to boot JavaStation computers. For your reference, 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 8-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 JavaOS). See Table 8-6 for more information.

IP Address Lease Time (51)  

LeaseTim

The duration of the IP address lease. A value of -1 indicates an infinite lease. After this period of time (expressed in seconds) has expired without being renewed, JavaOS shuts down the networking port. 

Subnet Mask (1)  

Subnet

The subnet mask. 

Time Server (4)  

Timeserv

The IP address of a server supporting the RFC 868 time port.  

Domain Name Server (6)  

DNSserv

The IP addresses of one or more DNS servers. JavaOS queries additional DNS servers if the primary server fails to respond.  

DNS Domain Name (40)  

DNSdmain

The DNS domain name. 

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

Table 8-4 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 8-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 JavaOS. 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 shown in Table 8-5 and is assumed to be in the TFTP root directory. See Table 8-6 for more information.

Root Path (17)  

Rootpath

The NFS-exported directory containing the JavaOS image. This option is used by the booter to locate JavaOS and by JavaOS 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 8-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, JavaOS uses router discovery to broadcast for a router.  

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 not given, JavaOS broadcasts looking for NIS servers. (This only works 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-4 and JOSchksm

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 clients, and the DHCP server has been configured to serve that class of clients, then the DHCP server can respond with a set of options that make sense only to that client type.

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

The delivery of Vendor-Specific Options to JavaStation clients works as follows. The DHCP client on the JavaStation (the PROM or JavaOS) includes the JavaStation'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 can deliver the JavaOS checksum and/or JavaOS property settings in the Vendor-Specific Options if it has been configured to do so.

The JavaStation's Client Class Identifier is specified in the PROM. Table 8-5 lists the Client Class Identifiers for each JavaStation model.

Table 8-5 JavaStation Client Class Identifiers

JavaStation Model 

Client Class Identifier 

Brick model 

SUNW.JDM1

Tower model 

SUNW.JSIIep

See "Sample dhcptab File "" for examples of setting the JavaOS checksum and JavaOS properties in dhcptab. Note, however, that JavaOS properties can be delivered to JavaOS using methods other than the DHCP Vendor-Specific Options. See Chapter 9, Setting JavaOS Properties for more information.

Sample dhcptab File

The following sample dhcptab file will supply 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. JOScmd1-4 can be used in macros that set JavaOS
# properties. JOSchksm is the JavaOS checksum. Refer to the
# dhcptab(4) man page for symbol definition syntax. 

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


# 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. 
# Notice also that the second JavaStation 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:

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 JavaOS, 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
  1. Determine the checksum.

    The checksum is contained in the first four bytes of the last 12 bytes of the JavaOS binary file. To determine the checksum, type:


    % tail -4c /export/root/javaos/JSIIep/javaos | od -xv \
    	| nawk '{print $2 $3}'
    14eb02a1 

  2. Use dhtadm to add the new checksum to the DHCP configuration.

    The command to add a new checksum is:


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

For example,


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

At boot up, each JavaStation will update its flash memory with the new JavaOS and then reboot using the new JavaOS.

To Disable JavaOS Updating
  1. Set the checksum to zero:


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

    or delete the checksum entirely from the DHCP configuration by typing:


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

    Note that there is nothing after the equal sign.

TFTP

Depending on how you set up the boot sequence, the TFTP server delivers either the booter or JavaOS to the JavaStation computers (see Table 8-1).

To Set Up a JavaStation TFTP Server
  1. Follow the instructions in the TCP/IP and Data Communications Administration Guide to configure a server on the network as a TFTP server.

    This guide is available at http://docs.sun.com. From the main web page, click the following links in the order shown.

    • System Administration

    • Solaris 2.6 System Administrator Collection, Volume 1

    • Setting Up and Administering TCP/IP Networks

    • Configuring TCP/IP on the Network

    • Configuring Standard TCP/IP Services.

    Also, refer to the inetd(1M) and in.tftpd(1M) man pages.

  2. Use dhtadm to add the relevant boot information to dhcptab, as described in Table 8-6:

    Table 8-6 DHCP Option Settings for TFTP

    If the TFTP server delivers.. 

    Set the following in dhcptab

    Relative Performance 

    the booter  

    • Set Bootfile to the path name of the booter file. The path name is assumed to be relative to the TFTP root directory. (If Bootfile is not set, the name of the booter file is assumed to be the Client Class Identifier - see Table 8-5.)

    • Set BootSrvA to the IP address of the TFTP server.

    • Set Rootpath to the directory on BootSrvA where the JavaOS image is located.

    preferred method (fastest) 

    JavaOS 

    • Set Bootfile to the path name of the JavaOS image. The path name is assumed to be relative to the TFTP root directory.

    • Set BootSrvA to the IP address of the TFTP server.

    • If flash update will be enabled, set Rootpath to the directory on BootSrvA where the JavaOS image is located.

    slow 

NFS

If a booter is used at the start of the boot process, the NFS server delivers the JavaOS image to the JavaStation computers.

To Set Up a JavaStation NFS Server
  1. Follow the instructions in the NFS Administration Guide to configure a server on the network as an NFS server.

    This guide is available at http://docs.sun.com. From the main web page, click the following links in the order shown.

    • System Administration

    • Solaris 2.6 System Administrator Collection, Volume 1

  2. Use dhtadm to set Rootpath to the directory on the NFS server where the JavaOS image is located.

HTTP

The HTTP (web) server delivers the user's main application to the JavaStation.

To Set Up a JavaStation Web Server
  1. Follow the vendor's instructions for setting up the web server.

  2. Prepare the application to be delivered to the JavaStation computers.

    See Chapter 10, Dynamically Loading Applications for instructions.

  3. Set JavaOS application loading properties.

    See Chapter 9, Setting JavaOS Properties and Chapter 10, Dynamically Loading Applications for information.