Peripherals for Sun Ray DTUs

C H A P T E R 4

This chapter contains information about selected USB, parallel, and serial devices and printing setup from Sun Ray DTUs.

Device Nodes and USB Peripherals

Mass Storage Devices

Attached Printers

PDA Synchronization

libusb

Serial peripherals enable RS-232-style serial connections to the Sun Ray DTU. Parallel peripherals enable printing and come in two types: adapters and direct USB-connected printers. Third-party adapters are useful for supporting legacy serial and parallel devices. Sun Ray Server Software recognizes parallel printers with adapters as USB printers.

For a list of supported serial and parallel devices and adapters, see: http://www.sun.com/io_technologies/sunray/sunray0.html

Note - The printer naming conventions in Sun Ray Server Software differ from those in a Solaris operating environment.

Device Nodes and USB Peripherals

Sun Ray Server Software creates a device directory called IEEE802.MACID in the /tmp/SUNWut/units directory. This directory contains the MAC address for each DTU on the interconnect. The IEEE802.MACID directory for each DTU contains dev and devices directories, analogous to the /dev and /devices directories in the Solaris operating environment. The Sun Ray dev directory contains a representation of the logical topology of the devices connected to the DTU. The Sun Ray devices directory contains a representation of the physical topology of some of the devices connected to the DTU.

Note - Sun Ray Server Software does not create device nodes for every USB device. Some USB device drivers export their device interfaces through other mechanisms than a traditional UNIX device node.

Directories correspond to buses and hubs, and files correspond to ports. Hub directories are named according to the port on the upstream hub into which they are attached.

Device Nodes

In Sun Ray devices, device nodes are created for each serial or printer port on an attached USB device. The device nodes are created in the hub directory corresponding to the hub to which they are attached. They are named:

 manufacturer_name, model_name@upstream_hub_port

If the USB device has multiple identical ports (for example, two serial ports), the name is followed by :n where n is a numerical index, starting at 1.

The following is a typical device node path:

/tmp/SUNWut/units/IEEE802.MACID/devices/usb@1/hub@1/\manufacturer_name, model_name@3:1

TABLE 4-1 Definitions of Naming Conventions
Term	Definition
physical topology	The physical topology is hub@port/hub@port and so on. The port refers to the port on the parent hub into which the device or child hub is plugged.
printer name 1, terminal name 1	The printer and terminal name in the Sun Ray `devices` directory is manufacturer, model@port with a colon separating the numerical index when the string just described is not unique in the directory.
printer name 2, terminal name 2	The printer and terminal name in the Sun Ray `dev` directory is the manufacturer and serial number concatenated with an alphabetic index when the serial number is not unique.

Device Links

Device links are created under the dev directory. A link to each serial node is created in dev/term, and a link to each parallel node is created in dev/printers.

Typical device links are:

/tmp/SUNWut/units/IEEE802.080020cf428a/dev/term/manufacturer_name-67a
/tmp/SUNWut/units/IEEE802.080020cf428a/dev/printers/1608b-64

manufacturer_name-serial_numberindex

where index is an increasing alphabetical character, starting at a.

If the manufacturer name is not available, the USB vendor and product ID numbers are used for the name of the device link.

Device Node Ownership

Some device nodes are owned by the user whose session is active on the DTU, while others may be owned by root or by other users that may have had previously active sessions on the DTU. Device permissions, access controls and ownership rules are determined by the class of device. For serial devices, only the user whose session is active on the DTU or the superuser have permission to use the attached device. If there is no user with an active session, superuser owns the serial and parallel device nodes. This rule may not hold for other classes of USB devices connected to the DTU.

Hotdesking and Device Node Ownership

The following description of the behavior of USB devices when sessions are connected and disconnected from a DTU applies only to USB serial and USB parallel devices. Other device classes may have different semantics regarding ownership and device lease times.

Changing the active session on a DTU changes the ownership of the device nodes to the user associated with the new session. A session change occurs whenever a user:

Inserts or removes a smart card from a DTU

Logs into a session

In a failover environment, you can use the utselect or utswitch command to change a session. A session change causes all devices currently open by a non-root user to be closed after 15 seconds. Any input or output to or from any affected device results in an error. Devices currently opened by the superuser, including normal Solaris printing, remain unaffected by the session change.

Note - When a session is changed, any input or output in progress on a serial device node opened by a non-root user is cancelled after 15 seconds. If the original session is restored within 15 seconds, the ownership is not relinquished, and input and output continue uninterrupted.

Mass Storage Devices

Device Nodes and Links

Mass storage devices have two types of device nodes, block and raw, which are created in the DTU’s device directory. A link to the block device is created in the DTU’s dev/dsk directory and a link to the raw device is created in the dev/rdsk directory.

Device links have a suffix denoting their slice number. Slice s2 is known as the backup slice, signifying the complete disk. Other slices are numbered accordingly on the file system on the disk. For UFS disks, slice numbers are derived from the disk label. For FAT disks, slices (partitions in this case) are numbered starting from s0. Disk operations such as format or eject should be directed at slice s2. Partition operations such as mount or fstyp should be directed at the individual slice concerned. See TABLE 4-2 for examples.

Mount Points

When a mass storage device is plugged into the DTU, if it has a Solaris-recognizable file system, it is automatically mounted on a directory under the user’s mount parent directory. The mount parent directory is located in $DTDEVROOT/mnt/. The user can also locate mount points by using the -l option to the utdiskadm command:

% utdiskadm -l

Device Ownership and Hotdesking

When the user’s session disconnects from the DTU, the user loses access rights to the mass storage device. All pending I/O to the device is aborted. This can cause the data on the device to be corrupted. Please advise users to use the utdiskadm command as follows to unmount all file systems safely before hotdesking or unplugging the disk from the DTU:

% utdiskadm -r device_name

Note - Before running this command, close all references to files and directories in the mount point to ensure that the device is not busy.

Mass Storage Devices and Idle Sessions

If a smart card or NSCM session (with RHA policy enabled) becomes idle due to keyboard and mouse inactivity long enough to activate the screen lock, the session is disconnected. The user loses access to the storage device, causing any I/O in progress to abort, and data may become corrupted.

To avoid this, users can:

Maintain keyboard or mouse activity

Increase the screen lock idle time sufficiently to allow I/O operations to complete

Disable the screen lock program

Disable the NSCM and/or RHA policies

Note - These options all have security and convenience implications that should be carefully weighed against the timeout issue to determine what is best for your site.

Common Disk Operations

TABLE 4-2 is a summary of common disk operations and the commands used to perform them. Refer to the Solaris System Administration Guide and man pages for more information on the individual commands.

TABLE 4-2 Commands for Common Disk Operation on SPARC and x86 Platforms
OPERATION	COMMAND	DEVICE NAME ARGUMENT EXAMPLES (SPARC)	DEVICE NAME ARGUMENT EXAMPLES (x86)
format	`rmformat(1)`	path of whole disk `$UTDEVROOT/dev/rdsk/disk3s2`	path of whole disk `$UTDEVROOT/dev/rdsk/disk3p0`
create file system	`mkfs(1M)`	path of partition `$UTDEVROOT/dev/rdsk/disk3s0`	path of partition `$UTDEVROOT/dev/rdsk/disk3p1`
create UFS file system	`newfs(1M)`	path of slice `$UTDEVROOT/dev/rdsk/disk3s0`	path of slice `$UTDEVROOT/dev/rdsk/disk3s0`
mount	`utdiskadm -m`	partition name `disk3s0`	partition name `disk3p1`
unmount	`utdiskadm -u`	mount point `$DTDEVROOT/mnt/label1`	mount point `$DTDEVROOT/mnt/label1`
prepare to unplug	`utdiskadm -r`	device alias `disk3`	device alias `disk3`
eject media	`utdiskadm -e`	device alias `disk3`	device alias `disk3`
check for media	`utdiskadm -c`	device alias `disk3`	device alias `disk3`
create fdisk table	`fdisk(1M)`	path of whole disk `$UTDEVROOT/dev/rdsk/disk3s2`	path of whole disk `$UTDEVROOT/dev/rdsk/disk3p0`
repair file system	`fsck(1M)`	path of raw slice `$UTDEVROOT/dev/rdsk/disk3s0`	path of raw partition `$UTDEVROOT/dev/rdsk/disk3p1`
display file system capacity	`df -k`	mount point `$DTDEVROOT/mnt/label1`	mount point `$DTDEVROOT/mnt/label1`
display slice capacity	`prtvtoc(1M)`	path of backup slice `$UTDEVROOT/dev/rdsk/disk3s2`	path of backup slice `$UTDEVROOT/dev/rdsk/disk3s2`
list devices	`utdiskadm -l`	none	none

Attached Printers

Sun Ray Server Software supports PostScript printers connected directly to a USB port on the Sun Ray DTU or connected through a USB-to-parallel port adapter. For non-PostScript printer support, refer to Non-PostScript Printers.

Note - The lp subsystem opens the device node as superuser for each print request, so print jobs are not affected by hotdesking.

For more information on Solaris Ready^TM printers, go to:

http://www.sun.com/solarisready/

Printer Setup

Starting a print queue on a printer attached to a Sun Ray DTU, either directly or through an adapter, is identical to starting a print queue in the Solaris operating environment.

To Set Up a Printer

1. Log in as superuser on a Sun Ray DTU.

2. To determine the MAC address of the DTU, press the three audio option keys to the left of the power key in the upper right corner of the keyboard.

The alphanumeric string displayed above the connection icon is the MAC address.

3. To locate the Sun Ray DTU, type:

# cd /tmp/SUNWut/units/*MAC_address
# pwd
 /tmp/SUNWut/units/IEEE802.MACID/

The path to the extended MAC address for your particular Sun Ray DTU is displayed.

4. Locate the port for the printer by typing:

# cd dev/printers
# pwd
/tmp/SUNWut/units/IEEE802.MACID/dev/printers
#ls
printer-node-name

5. In the directory, locate the printer node.

6. For Solaris 10, use the following steps:

a. Start the PrintManager by typing:

# /usr/sbin/printmgr &

b. Click OK to choose files for repository.

c. Go to Browse -> Printers -> Edit -> Add -> LocalPrinter.

d. Type in:

i. Printer name: printername

ii. Description (optional)

iii. Printer Port

Choose Other to enter the printer port path name. To locate the printer port, refer to Step 4 above.

7. To verify that the printer has been set up correctly, type:

# lpstat -d printername

Non-PostScript Printers

Printers that do not use PostScript, such as engineering plotters, are best supported by third-party software. Low-cost inkjet printers require third-party software such as:

Easy Software’s ESP PrintPro, available from http://www.easysw.com

Ghostscript, available from http://www.ghostscript.com

Vividata PShop, available from http://www.vividata.com

Check with the vendors for pricing and the precise printer models supported.

PDA Synchronization

PDASync for Solaris^TM requires a compatible version of the Java Communications API 2.0.2 or a later version to run on the Sun Ray DTU. Version 3 or later is recommended.

To synchronize PDAs that use the Palm OS to a Sun Ray DTU, use a USB-to-serial adapter.

Certain components of the Java Communications API package must be installed in specific directories for PDASync for Solaris to run.

To Set Up the PDASync Application on a Sun Ray DTU

1. Log in as superuser.

2. Get the latest Java Communications API (javax.comm api version 3 and above) from

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

3. Unzip the file by typing:

# unzip comm3.0_solaris.zip

4. Copy the CommAPI jar file into the PDAsync installation base by typing:

# cp commapi/jar/comm.jar  /usr/dt/appconfig/sdtpdasync/classes

5. Copy the CommAPI native library into the PDAsync installation base by typing:

# cp commapi/lib/libSolarisSerialParallel.so \
/usr/dt/appconfig/sdtpdasync/lib

6. Launch the PDASync application by typing:

# /usr/dt/bin/sdtpdasync

libusb

libusb is an Open Source user land USB API/library that enables an application to access USB devices. libusb has been implemented for a number of operating environments, including Linux, BSD, MacOS, and Windows, as well as for Solaris and Sun Ray environments.

libusb applications are capable of running on any operating environment that supports libusb. For further information, see /usr/sfw/share/doc/libusb/libusb.txt.

Some Open Source applications that make use of libusb support and enable users to access scanners, digital cameras, and other devices are listed below.

TABLE 4-3 Open Source `libusb` Applications
Application	URL	Comments
Sane	`http://www.sane-proj.org`	For scanner support
Gphoto	`http://www.gphoto.org`	For digital still cameras
ColdSync	`http://www.coldsync.org`	For Palm device support

For further information, please see:

http://sourceforge.net

Sun Download Center

The libusbut man page