Sun Ray Server Software 3 Administrator's Guide for the Solaris Operating System

This appendix contains the following sections:

• Understanding OSD
• Authentication Manager Errors
• Audio
• Troubleshooting USB Mass Storage Devices
• Performance Tuning
• Troubleshooting the Sun Management Center

---

Understanding OSD

Sun Ray Server Software on-screen displays (OSD) to help administrators and others identify problems visually. The most important information about the Sun Ray DTU and its current state is displayed on the screen.

OSD Icon Topography

• Ethernet address
• Currently assigned IP address of the DTU
• Link status of the currently connected Sun Ray server
• Authentication Server IP address
• Icon code and DHCP state

To help you locate problems, the OSD icons display a numeric icon code followed by an alphabetic DHCP state code. You can look up the meaning of the numeric OSD message codes in TABLE B-1 and the alphabetic DHCP state codes in TABLE B-2. Encryption and authentication information is also displayed when appropriate.

OSD icon messages and codes are summarized in the following tables:

Sun Ray Desktop Unit Startup

The first display a user should see is OSD 1: Waiting for the Interconnect.

1. Check that the Ethernet cable is correctly plugged in to the back of the DTU and the other end is plugged in to the correct hub, switch, or network outlet.

A link light on the switch or hub indicates that the connection is alive.

2. If the DTU is connected through a hub or a switch, make sure that the hub or switch is powered on and configured correctly.

After the Sun Ray desktop unit has verified its network connection, the user should see the DHCP Pending display.

1. Make sure that the DHCP server is configured correctly, is up and running, and has not run out of IP addresses to assign to clients.

2. Verify that your DHCP server is configured properly for network parameters.

At this point, depending on whether you have configured your Sun Ray servers to run on a LAN or a dedicated interconnect, one of the following icons may display:

After the DHCP server has allocated an IP address, the icon is updated with the unit's IP address; if the response is inadequate, the Sun Ray issues a DHCP inform request to attempt to obtain the Sun Ray vendor-specific parameters. The Sun Ray continues all the way through booting with just a DHCP supplied IP address but usually functions better with some additional parameters.

Code 21 B indicates that the DTU got an IP address and IP router and is waiting for Sun Ray vendor-specific options from DHCP inform.

1. For LAN configurations with other (non-Sun Ray) DHCP services but no bootp proxy agent, verify the DHCP server and the Sun Ray vendor tags.

2. For routed configurations, verify that the bootp proxy agent is configured correctly in the Sun Ray DTU's subnet and that it points to one of the Sun Ray servers in the failover group.

3. For non-routed private interconnect configurations, the Sun Ray server also performs the functions of a DHCP server. Verify that it is configured properly for DHCP services.

When DHCP has finished, the Sun Ray DTU tries to connect to a Sun Ray server and the authentication manager that is running on that server.

Waiting to Connect to Authentication Manager

Definition: The DTU has received its initial parameters from DHCP but has not yet connected to the Sun Ray Authentication Manager. This icon is displayed as part of the normal startup phase and is usually displayed for only a few seconds.

1. Make sure that the Sun Ray services, including the Authentication Manager, are up and running on the Sun Ray server.

In a LAN configuration or other routed environment:

2. Make sure that the authentication manager can be reached from the IP address assigned to the DTU.

3. Verify that the routing information the DTU receives is correct.

4. Run utquery for the DTU's IP address.

The utquery command displays the parameters a Sun Ray DTU has received. If utquery fails to display an AuthSrvr parameter, the DHCP server for Sun Ray parameters may not be reachable or may not be configured properly. Confirm that the DHCPServer and INFORMServer values are appropriate. If not, look at your bootp relay configurations and DHCP server configurations for network and Sun Ray parameters. For details of these parameters, see the utquery man page.

As superuser, type:

# /opt/SUNWut/sbin/utdesktop -l -w

As superuser, type:

# /opt/SUNWut/sbin/utsession -k -t token

Firmware Download

Definition: The DTU is currently downloading new flash PROM software from the Sun Ray server.

1. Wait until the download is complete.

Downloading and saving the new PROM software usually takes less than a minute. If you interrupt the download, the DTU has to download new PROM software the next time it reboots.

If the firmware download fails, the following syslog message indicates that the barrier level has been set to prevent Sun Ray DTUs with SRSS 3 firmware from automatically downloading an earlier version of the firmware:

Firmware upgrade/downgrade not allowed! Barrier is 300 Firmware level is 0

2. Check /var/opt/SUNWut/log/messages to confirm that your configuration is set up properly.

Saving PROM Software

Definition: The DTU has just downloaded new PROM software from the Sun Ray server and is saving it to the DTU's PROM.

Wait until the download is done.

Downloading and saving the new PROM software usually takes less than a minute. If you interrupt the download, the DTU has to download new PROM software the next time it reboots.

Firmware Download Failed

Definition: The DTU has failed to download new firmware.

1. Check the messages file /var/opt/SUNWut/log/messages to verify the version number.

2. Correct, if necessary, with utadm -l.

Bus Busy

Definition: The Sun Ray USB bus is temporarily busy servicing a high-speed device, and the keyboard or mouse may not be responsive to user input.

This icon typically appears only during an unusually long print job and disappears when the job is done. This is an informational OSD; there is no particular action to take unless it is necessary to kill the print job.

No Ethernet

No Ethernet Connection

Definition: The DTU has an Ethernet address and an IP address but has lost the Ethernet signal. This icon is displayed only after the DTU successfully boots and receives an IP address, but then loses its Ethernet signal.

1. Check that the Ethernet cable is correctly plugged in to the back of the DTU and the other end is plugged into the correct switch or network outlet.

2. If the DTU is connected through a hub or switch, make sure that the hub or switch is on and configured correctly.

Ethernet Address

Link speed is also indicated (for example, 10F, 10H,100F, 100H). F stands for full duplex, and H stands for half duplex. 10 stands for 10 Mbps, and 100 for 100 Mbps.

FIGURE B-1 Ethernet Address OSD with Different Encryption and Authentication States

Session Connection Failures

The following icons are displayed when there might be a security breach.

Definition: The client is refusing to connect to a server because it is unable to verify the validity of the Sun Ray server.

This error can occur only if an unknown Sun Ray server intercepts the messages and tries to emulate a valid Sun Ray server. This is a session security breach.

Session Refused

Definition: The server is refusing to grant a session to the client because the client is unable to fulfill the server's security requirements.

1. Check the client's firmware version.

This error may occur with firmware versions earlier than 2.0 if the server is configured for hard security mode.

2. Upgrade the firmware.

As an alternative, confirm whether your site requires hard security mode. If not, the session can be enabled with soft security mode.

Token Reader Icon

When a site policy disallows pseudo sessions, DTUs configured as token readers display the Card Reader icon instead of the Login Dialog box card.

Card Read Error OSD

Definition: The Card Read Error OSD icon appears whenever the firmware is unable to read the card due to one of the following causes:

• The DTU is running old firmware.
• The card contacts are dirty, the contacts on the card reader are dirty, or the card is not properly inserted.
• The card is malfunctioning.
• The card is of a type that the firmware is not configured to read.
• There is an error in the configuration for reading this type of card.

1. Upgrade the firmware.

2. Replace the card.

Prompt for Card Insertion OSD

Definition: If the current authentication policy allows access only by card, this OSD icon appears and prompts the user to insert a card.

Access Denied OSD

Definition: The Access Denied OSD icon appears when the current authentication policy denies access to the presented token. Specifically, this icon is displayed if a disabled card has been inserted into an DTU.

The Sun Ray administration model has seven user session types:

• Default--Normal user login
• Register--User self-registration
• Kiosk--Anonymous user operation
• Insert card--User smart card required
• Card error--Unrecognized user smart card type
• No entry--User's smart card token is blocked
• Session Refused--The server refuses to grant a session to a client that does not meet the server's security requirements

The first three session types have normal login processes. When there is a problem, the administrator should examine:

• Sun Ray Server configuration files

• Any locally modified X server startup files
• dtlogin status

Although the last four session types display icons on the Sun Ray DTU, they do not have login processes at all. The icons indicate that the user must take steps before a successful login is possible. If the user immediately removes and reinserts the smart card, the icon disappears, but the Wait for Session OSD remains.

These last four session types and their OSDs should not cause alarm. The user can:

• Insert a recognized smart card in the correct orientation
• Ask the Sun Ray administrator to grant access
• Ask the Sun Ray administrator to download the correct firmware

Wait for Session OSD

This OSD represents the transition state for the Sun Ray DTU. If it is displayed for an extended period, there is probably no X Window server running.

Wait Icon Cursor for Default Session Type

This section applies to a normal dtlogin session.

The Xsun server is indirectly started by the dtlogin daemon. In the process of starting the Xsun server, the dtlogin daemon reads two configuration files:

• /etc/dt/config/Xservers
• /etc/dt/config/Xconfig

If, after several retries, the Xsun process does not start, the dtlogin daemon just gives up. The problem can usually be traced back to an older version of the dtlogin daemon or the configuration files for the dtlogin daemon.

The dtlogin daemon has been part of the Solaris operating environment since long before Sun Ray Server Software existed. The Sun Ray administration model uses the dtlogin daemon in new ways, and certain bugs in the dtlogin daemon have become apparent. Patches to fix these bugs in the dtlogin daemon are available.

Patches

For the latest information regarding Sun Ray Server Software patches, check:

http://www.sun.com/products/sunray/patches.html

Solaris operating environment patches and other software patches are available at:

http://access1.sun.com

---

Authentication Manager Errors

Authentication Manager errors can be found in the following error logs:

• Installation logs:
• /var/adm/log
• /var/opt/SUNWut/log

• General log files:
• /var/opt/SUNWut/srds/log
• /var/opt/SUNWut/srds/replog

The general format of the log messages is:

timestamp   thread_name    message_class     message

For example:

May  7 15:01:57 e47c utauthd: [ID 293833 user.info] Worker3 NOTICE: SESSION_OK pseudo.080020f8a5ee

Message components are defined as follows:

• timestamp format:

year.month.day hours:minutes:seconds

• thread_name

There are several different types of threads. The most common thread handles DTU authentication, access control, and session monitoring. These threads are named "worker" plus number. The Worker# thread names are reused when a connection terminates. Other threads are:

• SessionManager#--Communicate with utsessiond on behalf of a Worker# thread.
• AdminJobQ--Used in the implementation to wrap a library that would not otherwise be thread-safe.
• CallBack#--Communicate with applications such as utload.
• WatchID--Used to poll data/terminals from connections
• Terminator--Cleans up terminal sessions
• Group Manager--Main group manager thread

• message_class

Messages with the same thread name are related. The exception occurs when a Worker# thread disconnects a DTU and then purges the connection information from memory. After a Worker# DESTROY message, the next use of that Worker# thread name has no relation to previous uses of the thread name (in other words, the thread names are reused).

• CLIENT_ERROR--Indicates unexpected behavior from a DTU. These messages can be generated during normal operation if a DTU is rebooted.
• CONFIG_ERROR--Indicates a system configuration error. The Authentication Manager generally exits after one of these errors is detected.
• NOTICE--Logs normal events.
• UNEXPECTED--Logs events or conditions that were not anticipated for normal operation but are generally not fatal. Some of these errors should be brought to the attention of the Sun Ray product development team.
• DEBUG--Only occurs if explicitly enabled. Beneficial to developers. Debug messages can reveal session IDs, which must be kept secret to ensure proper security.




TABLE B-4 Error Message Examples

Error class	Message	Description
CLIENT_ERROR	...Exception ... : cannot send keepAliveInf	Error encountered while attempting to send a keep-alive message to a DTU.
	...keepAlive timeout	A DTU has failed to respond within the allotted time. The session is being disconnected.
	duplicate key:	DTU does not properly implement the authentication protocol.
	invalid key:	DTU does not properly implement the authentication protocol.
CONFIG_ERROR	attempt to instantiate CallBack 2nd time.	Program error.
	AuthModule.load	Problem encountered while loading configuration module.
	Cannot find module	Program or installation error.
NOTICE	"discarding response: " + param	No controlling application is present to receive DTU response.
	"NOT_CLAIMED PARAMETERS: " + param	A token was not claimed by any authentication module.
	...authentication module(s) loaded.	Notification that authentication modules have loaded.
	...DISCONNECT ...	Normal notification of disconnection.
UNEXPECTED	"CallBack: malformed command"	Bad syntax from a user application such as utload or utidle.
	.../ ... read/0:" + ie	Possible program error.
	.../ ... read/1: ... Exception ...	Error encountered while reading messages from the DTU.
	.../... protocolError: ...	Various protocol violations are reported with this message. This is also a way for utauthd to force the DTU to reset.

---

Troubleshooting USB Mass Storage Devices

The most common problems encountered with USB mass storage devices on Sun Ray DTUs are described in the following sections.

Device Links Are Not Created

Some mass storage device types are not supported on Sun Ray. Inspect the log file /var/opt/SUNWut/log/utstoraged.log for an indication as to why device links were not created.

Device Is Not Automatically Mounted

If the storage medium does not have a Solaris-recognizable filesystem, it will not get automatically mounted. An error message will be logged to: /var/opt/SUNWut/log/utmountd.log

Device Is Not Automatically Unmounted

If the device is unplugged, or if the user's session is disconnected from the DTU, all mount points for that DTU are automatically unmounted unless the user has open references to the mount point. In that case, the mount point becomes stale. A stale mount point persists until the administrator unmounts it manually or until the system is rebooted.

Run the following command to find stale mount points.

# /opt/SUNWut/bin/utdiskadm -s

---

Audio

Each time a user logs in to a Sun Ray DTU, a script automatically assigns the $AUDIODEV environment variable to that session. One utaudio(1)real-time process is assigned to each session. Refer to the audio(7i)man page for more information.

Audio Device Emulation

The emulated audio device follows the user session during hot desking. The device name appears in the $AUDIODEV environment variable but is transparently interpreted by audio programs for Sun systems. Device nodes are created in the /tmp/SUNWut/dev/utaudio directory. The directory tree is completely recreated at boot time.

Caution - Do not remove the /tmp/SUNWut/dev/utaudiodirectory. Deleting this directory prevents existing users with utaudiosessions from using their audio pseudo device nodes.

If your application uses /dev/audio, the Sun Ray server software reroutes the audio signal appropriately.

Audio Malfunction

If audio features are malfunctioning:

1. To confirm whether audio is working, run the following command on the DTU:

% cat /usr/demo/SOUND/sounds/whistle.au >/$AUDIODEV

2. Bring up utsettings:

% utsettings

3. Verify that audio output is selected properly, e.g., for headphones or speakers.

4. Check the volume level.

5. Verify that Mute is not selected.

Some applications are hard-coded to use /dev/audio for output. Sun Ray System Software provides a redirection library that you can use to correct this behavior.

1. Set the environment variable LD_PRELOAD to libc_ut.so in the shell or wrapper from which you started the audio player:

# setenv LD_PRELOAD libc_ut.so

2. Restart the application.

---

PDA Synchronization Issues

If your users have problems running PDASync on a Sun Ray, use the following procedure:

3. Get the latest Java Communications API (javax.comm api version 3 or later) from

http://javax.sun.com/products/javacomm/

4. Make sure that you are using a supported USB-serial adapter.

A list of supported USB devices is available at:

http://www.sun.com/io_technologies/sunray/usb/

5. Click the change Synchronization Settings icon.

Select the port to which the Palm cradle is connected.

6. Click OK.

For setup instructions, see PDA Synchronization.

---

Performance Tuning

Some applications, such as intensive 3-D visual simulations, may run very slowly on Sun Ray. Other applications, such as pseudo-stereo viewers using double-buffering, or high-frequency dynamic color table flips on 8-bit visuals, do not produce the expected visual result.

General Configuration

You can usually improve performance by configuring /etc/system shared memory segment parameters. The exact settings depend on application demands and the number of Sun Ray users, but a convenient starting point is:

set shmsys:shminfo_shmmax = 0x2000000

set shmsys:shminfo_shmmni = 0x1000

set shmsys:shminfo_shmseg = 0x100

Due to the nature of the Xinerama (single virtual X display) mode of multihead, the system shared memory requirements may be even higher. To get reasonable performance, the shmsys:shminfo_shmmax parameter must be at least:

LARGEST_NUMBER_OF_HEADS * width * height * 4 

Applications

Placing the user's interactive applications, such as Netscape or StarOffice, or PC interoperability tools, such as Citrix or Tarantella, on the Sun Ray server usually helps performance by reducing network load. The applications benefit from faster transport of commands to the Sun Ray's X server.

Applications that can be configured to use shared memory instead of DGA or openGL usually perform better on Sun Ray when they used shared memory.

Sluggish Performance

Sluggish Sun Ray server performance or excessive disk swapping is an indication that the Sun Ray server is under-provisioned. Under these circumstances, there is not enough virtual memory available to start an X Window server instance for a user's session.

The solution in this situation is to add more memory or increase the size of the swap partition. In other situations, network load or packet loss may be too high. In very rare cases, network cables or switch equipment may be defective.

1. To determine whether there is excessive swapping, use vmstat 5.

# vmstat 5

If there is excessive swapping, the system may be undersized or overutilized.

2. Verify that network connections are 100F.

3. Use utcapture to assess network latency and packet loss.

As latency and packet loss increase, performance suffers.

Monitor Display Resolution Defaults to 640 x 480

First, eliminate the most obvious possible causes:

• An older monitor
• A bad cable
• Monitor was off when the Sun Ray DTU was started

If the Sun Ray DTU is unable to read DDC data from the monitor, then it defaults to 640 x 480 pixels.

To correct this condition:

1. Replace the cable

2. Restart the Sun Ray DTU after powering the monitor on

3. Replace the monitor

4. Use the utresadm to set persistent display setting to override the default.

Old Icons (Hourglass with Dashes Underneath) Appear on Display

If the old icons appear on the display, either the DTU's firmware has not been upgraded or it is failing.

1. Upgrade the firmware from to SRSS 3.

2. Follow the procedure to upgrade the firmware. See the Sun Ray Software 3 Installation and Configuration Guide.

You may need to use a dedicated private network.

Port Currently Owned by Another Application

If this message displays, use the following procedure to correct it:

1. Download the latest Java Communications API (javax.comm API version 2.0.2 and above)

2. Make sure that the supported USB-Serial Adapter is used.

The supported USB devices list is available at

http://www.sun.com/io_technologies/sunray/usb/

3. Click the Change Synchronization Settings icon and select the appropriate port (to which the Palm cradle should be connected), then click OK.

4. If the ports are not correctly shown in the Serial Port drop down menu, close the application and hot plug the device.

5. Start the application again.

Design Tips

• Avoid drawing into off-screen memory and then copying large areas to the screen. This technique produces slow Sun Ray performance.
• GXcopy mode is usually the fastest drawing mode.
• To display large images, use shared memory pixmaps, if possible.
• Opaque stipple patterns are faster than transparent stipples.
• Opaque (image) text is faster then other text.

---

Troubleshooting the Sun Management Center

Usually, if all the software is installed, the agent for Sun Ray monitoring starts automatically.

No Sun Ray Object

If the Sun Ray server has the Sun Management Center agent component installed, but the Detail window shows no Sun Ray object for the Sun Ray server node, load the Sun Ray module:

1. Click the Modules tab.

Note where the Sun Ray module is listed (if it is not listed, see No Sun Ray Module). For the module to be loaded, it should be listed in Modules with Load Status. In addition, it should be loaded and enabled.

FIGURE B-2 Module Panel

2. If the Sun Ray module is listed, highlight it and then click the Load button.

This loads the module and moves it to the Modules with Load Status list.

3. If the Sun Ray module is disabled, highlight it and then click the Enable button.

This enables the module.

4. Return to the Detail window.

The Detail window shows a Sun Ray object for the Sun Ray server node.

No Sun Ray Module

If, after clicking the Modules tab on the Details window of the Sun Ray server node, the Sun Ray module is not listed, activate the Sun Ray module:

1. Register the module by typing:

# /opt/SUNWut/sbin/utsunmc

This command adds the module to the Sun Management Center and restarts the agent if it is active.

2. If you receive the following message, perform steps 3 and 4.

Starting the SunMC agent...

NOTICE:         SunMC agent failed to start.

                To start it manually run the command

3. Check to see if the agent is running:

# ps -ef |grep agent

If the Sun Management Center agent is running, wait then check the Detail window.

4. If the agent is not running, type the following to start it:

# /opt/SUNWsymon/sbin/es-start -a

Sun Ray Server Software 3 Administrator's Guide for the Solaris Operating System

817-6806

Copyright © 2004, Sun Microsystems, Inc. All Rights Reserved.