This document gives advice on what to check, if a USB Mass Storage device fails
to operate on a Sun Ray[TM] thin client appliance.

1. Basic checks

It is recommended to go through the basic checks first.

1.1 Sun Ray Server Software(SRSS) Checks

1.1.1 Check both the OS and SRSS support

The following table shows USB Mass Storage on Sun Ray support matrix.

USB Mass Storage on Sun Ray, is not supported on SRSS 1.0, 1.1, 1.2, 1.3 or 2.0.
USB Mass Storage was available as an unsupported, unbundled download for SRSS 2.0.
In SRSS 3.0, USB Mass Storage is not supported with Controlled Access Mode.

See also

• InfoDoc 43122 "How to determine what version of Sun Ray [TM] Software is running on the server"
• InfoDoc 43763 "What is the FCS version of the Sun Ray[TM] Server Software?"

1.1.2 Check if the SRMS packages are installed

 # /usr/bin/pkginfo SUNWutsto SUNWutstr SUNWutstk
 system      SUNWutstk      Sun Ray server mass storage drivers (usr)
 system      SUNWutsto      Sun Ray server mass storage software (opt)
 system      SUNWutstr      Sun Ray server mass storage configuration (root)

1.1.3 Check if USB mass storage device access has been enabled

1.1.3.1 SRSS 3.0

In the SRSS 3.0, USB mass storage device access can only be either completely enabled, or completely disabled.

 # /opt/SUNWut/sbin/utusbadm
 DISABLED

To enable it run

 # /opt/SUNWut/sbin/utusbadm -e
 # /opt/SUNWut/sbin/utrestart -c

 # /opt/SUNWut/sbin/utusbadm
 ENABLED

1.1.3.2 SRSS 3.1

In the SRSS 3.1 the utusbadm command has been deprecated. By default, the USB
services are enabled. Use /opt/SUNWut/sbin/utdevadm command to enable/disable
USB services.

 # /opt/SUNWut/sbin/utdevadm

Sun Ray Device Service         Status
------------------------------ ------------
internal_serial                enabled
internal_smartcard_reader      enabled
usb                            disabled

To enable it, run

 # /opt/SUNWut/sbin/utdevadm -e -s usb
 # /opt/SUNWut/sbin/utrestart -c

 # /opt/SUNWut/sbin/utdevadm

Sun Ray Device Service         Status
------------------------------ ------------
internal_serial                enabled
internal_smartcard_reader      enabled
usb                            enabled

1.2 Sun Ray[TM] DTU Checks

1.2.1 Check if it is a Sun Ray[TM] DeskTop Unit(DTU) with P1 motherboard

 % /opt/SUNWut/sbin/utdesktop -p <mac address> | grep -i model
   Model                 = SunRayP1

In this case, the DTU has a P1 motherboard.
P1 hardware is somewhat old, and sometimes cannot deliver full power to its USB
connectors. Only the P1 had this problem, not all Sun Ray 1 appliances. If you
need to drive USB peripherals, then it is a good idea to make sure the DTU does
not have P1 hardware. Try the mass storage device on a Sun Ray[TM] DTU with a
newer model.

See also

• InfoDoc# 26428 "How to find the MAC address of the Sun Ray[TM] appliance currently logged into".

1.2.2 Check that the DTU has a firmware from at least SRSS 3.0

It may not work with older firmware revisions

 % /opt/SUNWut/sbin/utdesktop -p <mac address> | grep -i firmware
   Firmware Revision     = 3.0_51,REV=2004.11.10.16.18

In the case above, the DTU has the minimum required firmware (3.0_51).

See also

• InfoDoc# 41563 "How to manage the Firmware on a Sun Ray[TM] unit"

1.3 Connection Checks

1.3.1 General connection checks

Make sure all cables are connected. The USB specification limits the length
of a cable between full speed devices, to 5 meters(16 feet, 4.85 inches).
Make sure the cable is not longer.

For troubleshooting, do not use USB-Repeater or USB-Line-Extender.

1.3.2 USB hubs

USB hubs can be bus powered(they get the power by the USB cable) or self
powered(they get the power by an external power supply unit).

If connected to a self-powered USB hub, ensure the hub is connected correctly,
and has power.

Do not use a bus-powered hub between the storage device and the DTU, because a
USB port can offer only max. 500 mA, and there are many USB devices which
require up to 500 mA when fully operational. In the worst case, it can result in
data corruption if a bus-powered hub is used.

For troubleshooting, we recommend connecting the USB device directly rather than
using a USB hub in between.

1.4 Mass Storage Checks

1.4.1 Check if the mass storage is a supported device

Sun Ray Server Software 3.x on Solaris supports the use of Flash Disks (e. g.
Memory Sticks), Memory Card Readers, Zip drives, and Hard Drives on Sun Ray
DTUs. SRSS 3.x does not support floppy drives.

Sun Ray Server Software 3.0 on Solaris does not support CD or DVD drives.

Sun Ray Server Software 3.1 on Solaris allows data CDs and DVDs to be read but not written.

Support for some of the "not supported device types" might come in the future.
Other devices we know, that we have had trouble with are: "Butterfly media flash
drive" and various "SanDisk devices". These run a different protocol,.

Go to http://www.sun.com/io_technologies/sunray.html for a list of mass
storage devices that have been verified by Sun.

1.4.2 Check if your mass storage has a supported file system

Supported file systems are UFS and PCFS.

Note: FAT partitions and UFS slice names have sn suffixed to them to denote traditional SunOS slices, e.g. disk1s0, disk1s6.
disk1s2 is the backup slice (full disk, similar to c3t0d0s2 in /dev/dsk).

See also:

• http://docs.sun.com/app/docs/doc/817-6960/6mmah9472?a=view

2. Checks for a Specific Problem

It is recommended to go through the basic checks first, even if there is a
specific problem.

2.1 Mount Problems

You plugged in a flash disk at your Sun Ray[TM] appliance, and nothing happened.

Here is how to find out what went wrong.

2.1.1 Check, if a mount point has been created under $DTDEVROOT/mnt

 % cd $DTDEVROOT/mnt
 % pwd
 /tmp/SUNWut/mnt/guest
 % ls -d disk*
 disk2
 % ls -la disk*
 lrwxrwxrwx   1 root   root   28 Jan 14 12:35 disk2 -> /tmp/SUNWut/mnt/guest/noname

2.1.2 Did the mass storage service (utstoraged) create device links in $UTDEVROOT/dev/dsk ?

 % cd $UTDEVROOT/dev/dsk
 % pwd
 /tmp/SUNWut/units/IEEE802.0003ba5b56f1/dev/dsk
 % ls -la
 total 48
 drwxr-xr-x   2 root     other     181 Jan 14 12:35 .
 drwxr-xr-x   4 root     root      238 Jan 14 12:35 ..
 lrwxrwxrwx   1 root     other     72 Jan 14 12:35 disk2s2 -> 
../../devices/usb@1/hub@4/USB_2.0_Flash_Disk,USB_Mass_Storage_Device@2:2

If device links exist, but the device is not mounted, it is possible that
the disk does not have a Solaris OS recognizable filesystem on it. This could be
because:

• It has a FAT filesystem that Solaris PCFS does not understand
• It has no filesystem. Format the disk, and create new filesystem using mkfs
  in this case

If device links do not exist, it could mean that the disk is running a USB
protocol not recognized by utstoraged. If utstoraged was started up with debug
turned on (utstoraged -D 20 is default beta startup level), look for the
following messages in utstoraged.log.

• USB sub-class 0x.. not supported
• USB protocol 0x.. not supported

You will have to wait for a future release of utstoraged to implement the remaining USB protocols.

2.1.3 Is the mass storage service up and running ?

 # ps -ef | grep utstoraged
     root 18473 18471  0 12:34:39 ?        0:00 /opt/SUNWut/lib/utstoraged -r
     root 18474 18473  0 12:34:39 ?        0:00 /opt/SUNWut/lib/utstoraged -r
     root 18471     1  0 12:34:39 pts/7    0:00 /bin/ksh -p /opt/SUNWut/lib/utlog -o /var/opt/SUNWut/log/utstoraged.log

If the daemons are not running, start up services with:

 # /etc/init.d/utstorage start
 starting mounter service
 starting storage service

2.1.4 Is the mounter daemon is up and running ?

 # ps -ef | grep utmountd
     root 18470 18469  0 12:34:39 pts/7    0:00 /opt/SUNWut/lib/utmountd
     root 18469     1  0 12:34:39 pts/7    0:00 /bin/ksh -p /opt/SUNWut/lib/utlog -o /var/opt/SUNWut/log/utmountd.log

If the daemon is not running, start up services with:

 # /etc/init.d/utstorage start

 starting mounter service

2.2 Write Problems

If there are problems writing on the mass storage, check if it has hardware
write protection enabled. Search for a little plastic switch on memory sticks,
for example.

2.3 Performance Problems

2.3.1 Slow-, Full- and High-speed USB devices

Sun Ray appliances provide four USB 1.1 ports, or (in the new USB terminology)
full-speed ports, which talk to devices at either 1.5 Mbit/s or 12 Mbit/s,
depending on the preference of the device. Slow-speed devices like Keyboards and
Mice, prefer the 1.5 Mbit/s subchannel, for example.

USB 2.0 (known as high-speed USB) products, have a design data rate of 480
Mbit/s. Current Sun Ray hardware does not support USB 2.0 - but, don't worry
about devices claiming USB 2.0 compliance. USB is both upwards- and
backwards-compatible. You can attach USB 2.0 hardware also to a Sun Ray
appliance, the device will work, but slower.

2.3.2 Accessing Large File Systems

Sun Ray[TM] Mass Storage is intended for low data rate and low duty cycle uses.
For example, personal storage of small files, file transfer to/from disconnected
computers, archival storage/retrieval of modest amounts of data would be
appropriate uses. Attempting to use USB mass storage on a Sun Ray[TM] to mount a
huge general use file system or a sizeable production database is not appropriate.

2.3.3 Latency

The Sun Ray[TM] USB protocol is tuned for low latency and does not perform well
in other environments.

2.3.4 Low bandwidth environments

Using USB mass storage devices in a Sun Ray[TM] low bandwidth environment works
over non-NAT connections, and is fine for limited use, within the limitations
imposed by the low available network bandwidth. At 300-1000 Kbit/s, it would
take a long time to write a sizeable amount of data, which could also impact
graphics performance of all user sessions sharing the same connection or line to
the Sun Ray[TM] server.

2.3.5 Other potential hardware issues

Do not use a Sun Ray[TM] with a P1 type motherboard. See also 1.2.1.
Do not use USB hubs. See also 1.3.2.

2.4 Unmount Problems

2.4.1 Device is busy

 % /opt/SUNWut/bin/utdiskadm -r disk1
 utdomount: /tmp/SUNWut/mnt/guest/unamed: Device busy
 utdiskadm: unmount /tmp/SUNWut/mnt/guest/unnamed failed

 % pwd
 /tmp/SUNWut/mnt/guest/unnamed

Place the working directory outside the mounted directory to fix the problem
above.

 % cd /
 % /opt/SUNWut/bin/utdiskadm -r disk1
 disk1 is ready for unplugging

2.5 Sync Problems

If your Palm won't sync with the Sun Ray, do the following:

  # cd /usr/sfw/lib/libusb_plugins
  # ln -s /opt/SUNWut/lib/libusbut.so.1 libusbut.so

3. Log Files

3.1 Check the logs for errors

Have a look in the log files. Sometimes there is useful information which can
narrow down the problem.

• utstoraged dumps messages to /var/opt/SUNWut/log/utstoraged.log
• utmountd dumps messages to /var/opt/SUNWut/log/utmountd.log
• The kernel modules dump messages to /var/adm/messages
• Run /opt/SUNWut/bin/utdiskadm -s as root to see a list of stale mount points

3.2 Set debug levels

• utstoraged debug level can be set by editing /etc/init.d/utstorage and setting the value for -D
• utmountd debug level can be set by editing /etc/init.d/utstorage and setting the value for -D
• Kernel module debug level can be set by changing the value of the utdebug property in /usr/kernel/drv/utdiskctl.conf and
  reloading the module as follows
  o /etc/init.d/utstorage stop
  o /usr/sbin/modinfo | grep utdisk (to find module ID)
  o /usr/sbin/modunload -i <utdisk_module_id>
  o /usr/sbin/update_drv utdiskctl
  o /usr/sbin/update_drv utdisk
  o /etc/init.d/utstorage start

Appendix

References:
o http://www.sun.com/io_technologies/sunray.html
o http://www.usb.org
o So you actually wanted to use your iPod with Solaris 10?!

Abbreviations:
o DTU Desktop Unit
o GA General Availability
o NAT Network Address Translation
o OS Operating System
o PCFS Personal Computer File System
o SRMS Sun Ray Mass Storage
o SRSS Sun Ray Server Software
o USB Universal Serial Bus