C H A P T E R  2

Command-Line Interface

The Command-Line Interface (CLI) is the recommended interface for enabling assistive technologies.

This chapter contains the following information:

Supported Commands

Commands that can be executed from the command line are listed in TABLE 2-1, and a few of the most important commands are documented in this chapter. For further information on executing these commands, see the man page for the command in question.

To view any of the specific commands for the Sun Ray system, type:
or type:

% man -M  /opt/SUNWut/man command

% setenv MANPATH=/opt/SUNWut/man
% man command

TABLE 2-1 Supported Commands




The utaction program provides a way to execute commands when a Sun Ray DTU session is connected, disconnected, or terminated.


The utadm command manages the private network, shared network, and DHCP (Dynamic Host Configuration Protocol) configuration for the Sun Ray interconnect.


The utadminuser command is used to add, list, and delete UNIX user names from the list of users authorized to administer Sun Ray services. The list is stored in the Sun Ray data store.


The utamghadm command is used to configure or disable regional hotdesking, which enables users to access their sessions across multiple failover groups.


The utcapture command connects to the Authentication Manager and monitors packets sent and packets dropped between the Sun Ray server and the Sun Ray DTUs.


The utcard command allows configuration of different types of smart cards in the Sun Ray data store


The utconfig command performs the initial configuration of the Sun Ray server and supporting administration framework software.


The utcrypto command is a utility for security configuration.


The utdesktop command allows the user to manage Sun Ray DTUs connected to the Sun Ray server that the command is run on.


The utdetach command disconnects the current non-smart card mobile session or authenticated smart card session from its respective Sun Ray DTU. The session is not destroyed but put into a detached state. The session can be accessed if the same user token (user name) is presented to the Sun Ray server.


The utdevadm command is used to enable/disable Sun Ray device services. This includes USB devices connected through USB ports, embedded serial ports, and internal smart card reader in the Sun Ray DTU.


The utdiskadm utility is a tool for Sun Ray mass storage administration.


The utdssync command converts the port number for the Sun Ray Data Store service to the new default port on servers in a failover group, then forces all servers in the group to restart Sun Ray services.


The uteject command is used to eject media from a removable storage media device.


The utfwadm command manages firmware versions on the Sun Ray DTUs.


The utfwload command is used primarily to force the download of new firmware to a DTU running older firmware than its server.


The utfwsync command refreshes the firmware level on the Sun Ray DTUs to what is available on the Sun Ray servers in a failover group. It then forces all the Sun Ray DTUs within the group to restart.


The utgroupsig command sets the failover group signature for a group of Sun Ray servers. The utgroupsig command also sets the Sun Data Store rootpw used by Sun Ray to a value based on the group signature. Although utgroupsig sets the rootpw in the utdsd.conf file, it does not set the admin password, which is a separate entity, in the data store.


The utgstatus command allows the user to view the failover status information for the local server or for the named server. The information that the command displays is specific to that server at the time the command is run.


The utinstall utility installs, upgrades, and removes Sun Ray Server Software. All software required to support the Sun Ray server is installed, including the administration framework.


The utkiosk tool is used to import/export kiosk configuration information into the data store.


The utkioskoverride command provides a way to set the session type associated with a token or to query the session type currently associated with a token.


The utmhadm command provides a way to administer Sun Ray server multihead terminal groups. The information that utmhadm displays and that is editable is stored in the data store.


The utmhconfig tool allows an administrator to list, add, or delete multiheaded groups easily.


The utmount command is used to mount a file system on a Sun Ray mass storage device.


The utpolicy command sets and reports the policy configuration of the Sun Ray Authentication Manager, utauthd(1M). This command’s -i and -t options were deprecated as of the 2.0 release. Continue to use the utpolicy command for policy changes, but use the utrestart command instead of utpolicy -i, and use utreader instead of utpolicy -t.


The utpreserve command saves existing Sun Ray Server Software configuration data to the /var/tmp/SUNWut.upgrade directory.


The utpw command changes the Sun Ray administrator password (also known as the UT admin password) used by the Web-based and command-line administration applications.


The utquery command collects DHCP information from the Sun Ray DTUs.


The utreader command is used to add, remove, and configure token readers.


The utreplica command configures the Sun Ray Data Store server to enable replication of administered data from a designated primary server to each secondary server in a failover group. The data stores of the secondary servers remain synchronized automatically unless there is a power outage. The -z option is useful for updating the port number.


The utresadm command allows an administrator to control the resolution and refresh rate of the video monitor signal (persistent monitor settings) produced by the Sun Ray unit.


The utresdef command allows an administrator to create, delete, and view resolution definitions (actually monitor signal timing definitions) for monitors attached to Sun Ray DTUs.


The utrestart command is used to start Sun Ray services.


The utselect command presents the output of utswitch -l as a list of servers in the current host group, to be used for reconnection of the current DTU. A user can either select a server from this list or specify a server not in the current host group by typing its full name in the utselect text box.


The utsession command lists and manages Sun Ray sessions on the local Sun Ray server.


Use utset to view and change Sun Ray DTU settings.


The utsettings command opens a Sun Ray Settings dialog box that allows the user to view or change audio, visual, and tactile settings for the Sun Ray DTU.


The utswitch command allows a Sun Ray DTU to be switched among various Sun Ray servers. utswitch can also list existing sessions for the current token.


The utumount command is used to unmount a file system from a Sun Ray mass storage device.


The utuser command allows the administrator to manage Sun Ray users registered on the Sun Ray server that this command is run on. It also provides information on the currently inserted token (smart card) for a specified DTU that is configured as a token reader.


The utwall utility sends a message or an audio file to users having anXnewt (X server unique to Sun Ray) process. The messages can be sent in email and displayed in a pop-up window.


The utwho script assembles information about display number, token, logged-in user, etc., in a compact format.


The utxconfig program provides X server configuration parameters for users of Sun Ray DTU sessions.

procedure icon  To Stop Sun Ray Services

single-step bullet  Type:

# /etc/init.d/utsvc stop

procedure icon  To Start Sun Ray Services

single-step bullet  Type:

# /opt/SUNWut/sbin/utrestart

This procedure, known as a warm restart, starts Sun Ray services without clearing existing sessions.


single-step bullet  Type:

# /opt/SUNWut/sbin/utrestart -c

This procedure, known as a cold restart, starts Sun Ray services and clears existing sessions.

Session Redirection

After a user’s token has been authenticated, whether via smart card token or direct login, it is automatically redirected to the appropriate server. To redirect a session to a different server manually, use the utselect graphical user interface (GUI) or the utswitch command.

procedure icon  To Redirect to a Different Server

single-step bullet  From a shell window on the DTU, type:

% /opt/SUNWut/bin/utselect

The selections in the window are sorted in order of the most current to least current active sessions for the token ID.

In FIGURE 2-1, the Server column lists the servers accessible from the DTU. The Session column reports the DISPLAY variable X session number on the server if one exists. In the Status column, Up indicates that the server is available. The first server in the list is highlighted by default. Select a server from the list or enter the name of a server in the Enter server: field. If a server without an existing session is selected, a new session is created on that server.

FIGURE 2-1 The Server Selection (utselect) GUI

This screen allows the user to select a server in a failover group

The OK button commits the selection of the highlighted or manually entered server. The Cancel button dismisses the GUI without making any changes to the session. The Refresh button reloads the window with the most current information.

procedure icon  To Redirect a DTU Manually

single-step bullet  From a shell window on the DTU, type:

% /opt/SUNWut/bin/utswitch -h host [ -k token] 

where host is the host name or IP address of the Sun Ray server to which the selected DTU is redirected, and token is the user’s token ID.

procedure icon  To List Available Hosts

single-step bullet  From a shell window, type:

% /opt/SUNWut/bin/utswitch -l

Hosts available from the Sun Ray DTU are listed.

procedure icon  To Select a Server with the Latest Session

single-step bullet  In a shell window, type:

% /opt/SUNWut/bin/utswitch -t 

The DTU is redirected to the server with the latest session connect time.

Managing User Data in the Sun Ray Data Store

You can specify the following user fields in the Sun Ray data store:

TABLE 2-2 Key User Fields



Token ID

User’s unique token type and ID. For smart cards, this is a manufacturer type and the card’s serial ID. For DTUs, this is the type “pseudo” and the DTU’s Ethernet address. Examples:


Server Name

Name of the Sun Ray server that the user is using.

Server Port

Sun Ray server’s communication port. This field should generally be set to 7007.

User Name

User’s name.

Other Info

Any additional information you want to associate with the user (for example, an employee or department number). This field is optional.

Note - Sun Ray Server Software now supports multiple administration accounts. This feature is described in Enabling Multiple Administration Accounts.

Changing Authentication Policies

When you set an authentication policy with utpolicy, the failover group policy is set automatically, so all that is needed at that point is to reset or restart services. The Admin GUI’s System Policy tab refers to authentication policy.

TABLE 2-3 utrestart Commands




Use this option if a minor policy change was made, such changing from soft to hard security mode. With minor changes, it is not necessary to terminate existing sessions. This is a warm restart.

/opt/SUNWut/sbin/utrestart -c

Use this option if a significant policy change has been made, such as enabling or disabling access to mass storage devices. All existing sessions are terminated. This is a cold restart.

Enabling Multiple Administration Accounts

Early releases of Sun Ray Server Software allowed only one user account, admin, to modify entries in the Sun Ray Data Store. Now, however, the administrator can allow any valid UNIX user ID in the authorized user list to administer Sun Ray services. An audit trail of activity on these accounts is provided. See the man page for utadminuser(1M).

Authentication for accounts with administrative privileges is based on the PAM authentication framework.

PAM Entries

In order to support the old Data Store authentication, a PAM module, /opt/SUNWut/lib/pam_sunray_admingui.so.1, is included in the Sun Ray product.

procedure icon  To Configure UNIX Users

To configure the Sun Ray Admin GUI to use UNIX user names instead of the default admin account:

single-step bullet  Copy the auth entries from /etc/pam.d/login file into /etc/pam.d/utadmingui:

Note - Make sure to include the comment line, which is needed for the cleanup to work properly.

procedure icon  To Revert to the Old admin User

To return to the old Sun Ray Admin GUI authentication scheme:

single-step bullet  Replace the PAM entries in the /etc/pam.d/utadmingui file with the pam_sunray_admingui.so.1 module:

# added to utadmingui by Sun Ray Server Software -- utadmingui
    auth sufficient /opt/SUNWut/lib/pam_sunray_admingui.so.1

Note - Make sure to include the comment line, which is needed for the cleanup to work properly.

Administration GUI Audit Trail

The administration framework provides an audit trail of the Administration GUI. The audit trail is an audit log of the activities performed by multiple administration accounts. All events that modify system settings are logged in the audit trail.

SRSS 4.0 uses the syslog implementation. Events are logged into /var/opt/SUNWut/log/messages file, where audit events are prefixed with the keyword utadt:: so that administrator can filter events from the messages file.

For example, session termination from the Admin GUI generates the following audit event:

Jun  6 18:49:51 sunrayserver usersession[17421]: [ID 521130 user.info] utadt:: username={demo} hostname={sunrayserver} service={Sessions}
cmd={/opt/SUNWut/lib/utrcmd sunrayserver /opt/SUNWut/sbin/utsession -x -d 4 -t Cyberflex_Access_FullCrypto.1047750b1e0e -k 2>&1}
message={terminated User "Cyberflex_Access_FullCrypto.1047750b1e0e" with display number="4" on "sunrayserver"}
status={0} return_val={0}




User’s Unix ID



Host on which the command is executed



Name of the service being executed



Name of the command being executed



Details about the action being performed

Enabling and Disabling Device Services

Sun Ray device services can be enabled and disabled with the utdevadm command line tool or with the Admin GUI. Sun Ray device services include USB devices connected through USB ports, internal serial ports, and internal smart card readers on the Sun Ray DTU. Device services can also be administered from the Security tab on the Admin GUI’s Advanced tab.

The Sun Ray 2 and Sun Ray 2FS each have one embedded serial port; the Sun Ray 170 and Sun Ray 270 each have two embedded serial ports. When internal serial service is disabled, users cannot access embedded serial ports on the Sun Ray DTU.

When internal smart card reader service is disabled, users cannot access the internal smart card reader through the PC/SC or SCF interfaces for reading or writing; however, this does not affect session access or hotdesking with unauthenticated smart cards.

When USB service is disabled, users cannot access any devices connected to USB ports. This does not, however, affect HID devices such as the keyboard, mouse, or barcode reader.

After installation of Sun Ray Server Software, all device services are enabled by default. You can use the utdevadm command to enable or disable device services only in the configured mode, that is, after the Sun Ray Data store is activated.

This configuration affects all the servers in a group and all the DTUs connected to that group.

The following example shows how to enable or disable USB service. The other device services can be enabled or disabled with the same syntax.

procedure icon  To Determine the Current State of Device Services

single-step bullet  Use the utdevadm command:

# /opt/SUNWut/sbin/utdevadm

This displays enabled or disabled state of the devices.

procedure icon  To Enable USB Service

single-step bullet  Use the utdevadm command as below:

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

procedure icon  To Disable USB Service

single-step bullet  Use the utdevadm command as below:

# /opt/SUNWut/sbin/utdevadm -d -s usb

procedure icon  To Perform a Cold Restart

single-step bullet  Use the utrestart command as below:

# /opt/SUNWut/sbin/utrestart -c

Configuring Interfaces on the Sun Ray Interconnect Fabric

Use the utadm command to manage the Sun Ray interconnect fabric.

Note - If the IP addresses and DHCP configuration data are not set up properly when the interfaces are configured, then the failover feature will not work as expected. In particular, configuring the Sun Ray server’s interconnect IP address as a duplicate of any other server’s interconnect IP address may cause the Sun Ray Authentication Manager to generate “Out of Memory” errors.

Note - If you make manual changes to your DHCP configuration, you will have to make them again whenever you run utadm or utfwadm.

procedure icon  To Add an Interface

single-step bullet  Type:

# /opt/SUNWut/sbin/utadm -a interface_name

This command configures the network interface interface_name as a Sun Ray interconnect. Specify a subnet address or use the default address, which is selected from reserved private subnet numbers between and

Note - If you choose to specify your own subnet, make sure it is not already in use.

After an interconnect is selected, appropriate entries are made in the hosts, networks, and netmasks files. (These files are created if they do not exist.) The interface is activated.

Any valid network interface can be used. For example:

eth0, eth1, eth2

procedure icon  To Delete an Interface

single-step bullet  Type:

# /opt/SUNWut/sbin/utadm -d interface_name

This command deletes the entries that were made in the hosts, networks, and netmasks files and deactivates the interface as a Sun Ray interconnect.

procedure icon  To Print the Sun Ray Private Interconnect Configuration

single-step bullet  Type:

# /opt/SUNWut/sbin/utadm -p

For each interface, this command displays the hostname, network, netmask, and number of IP addresses assigned to Sun Ray DTUs by DHCP.

Note - Sun Ray servers require static IP addresses; therefore, they cannot be DHCP clients.

procedure icon  To Add a LAN Subnet

single-step bullet  Type:

# /opt/SUNWut/sbin/utadm -A subnet_number

procedure icon  To Delete a LAN Subnet

single-step bullet  Type:

# /opt/SUNWut/sbin/utadm -D subnet_number

procedure icon  To Print Public LAN Subnets

single-step bullet  Type:

# /opt/SUNWut/sbin/utadm -l

procedure icon  To Remove All Interfaces and Subnets

Use the utadm -r command to prepare for removal of the Sun Ray Server Software.

single-step bullet  Type:

# /opt/SUNWut/sbin/utadm -r

This command removes all of the entries and structures relating to all of the Sun Ray interfaces and subnets.

Managing Firmware Versions

Use the utfwadm command to keep the firmware version in the PROM on Sun Ray DTUs synchronized with that on the server. See also Firmware Download.

Note - If the DHCP version variable is defined, then when a new DTU is plugged in, its firmware is changed to the firmware version on the server.

Note - If you make manual changes to your DHCP configuration, you will have to make them again whenever you run utadm or utfwadm.

procedure icon  To Update All the DTUs on an Interface

single-step bullet  Type:

# /opt/SUNWut/sbin/utfwadm -A -a -n interface

Tip - To force a firmware upgrade, power-cycle the DTUs.

procedure icon  To Update a DTU Using the Ethernet (MAC) Address

single-step bullet  Type:

# /opt/SUNWut/sbin/utfwadm -A -e MAC_address -n interface

Restarting the Sun Ray Data Store (SRDS)

If you restart the Sun Ray Data Store daemon (utdsd), you must also restart the Sun Ray Authentication Manager. The Sun Ray Data Store daemon may need to be restarted if you change one of its configuration parameters. The following procedure shows the correct order of the steps to take if you need to restart SRDS.

procedure icon  To Restart Sun Ray Data Store

1. Stop the Sun Ray services:

# /etc/init.d/utsvc stop

2. Stop the Sun Ray Data Store daemon:

# /etc/init.d/utds stop

3. Restart the Sun Ray services:

# /opt/SUNWut/sbin/utrestart

Smart Card Configuration Files

Use the Administration Tool or the utcard command to add additional smart card vendor configuration files.

Smart card configuration files are available from a variety of sources, including Sun and various of smart card manufacturers.

procedure icon  To Load a Configuration File Into the Directory

single-step bullet  Copy the vendor configuration file containing the vendor tags to the following location:

# cp vendor.cfg /etc/opt/SUNWut/smartcard

The additional vendor cards are displayed under the Available Smart Cards column in the Card Probe Order tab in the Administration Tool.

Configuring and Using Token Readers

Some manufacturers print the smart card ID on the card itself, but many do not. Since all the administrative functions refer to this token ID, Sun Ray Server Software provides a way to designate one or more specific DTUs as dedicated token readers. Site administrators can use a dedicated token reader to administer Sun Ray users through their tokens. A token reader is not used for normal Sun Ray services, so it does not need a keyboard, mouse, or monitor.

Note - When you enable an authentication policy with registered users, or token owners, be sure to specify smart card IDs for the appropriate token owners.

In the example configuration in FIGURE 2-2, the second DTU acts as a token reader.

FIGURE 2-2 Using a Token Reader to Register Smart Cards

Server, token reader, and DTU all connected to the same switch

procedure icon  To Configure a Token Reader

The utreader command specifies a DTU for registering smart cards. When a DTU is configured as a token reader, inserting or removing a smart card does not cause session mobility to occur; instead, any session connected to the DTU remains connected to that DTU over a card movement event.

Token reader mode is useful when you want to determine the raw token ID of a smart card.For example, to configure the DTU with MAC address 0800204c121c as a token reader, issue the following utreader command:

# /opt/SUNWut/sbin/utreader -a 0800204c121c

To re-enable the DTU with MAC address 0800204c121c to recognize card movement events and perform session mobility based on the smart card inserted into the DTU:

# /opt/SUNWut/sbin/utreader -d 0800204c121c

To unconfigure all token readers on this server:

# /opt/SUNWut/sbin/utreader -c

procedure icon  To Get a Token ID From a Token Reader

In releases prior to SRSS 3, access to the token card reader was limited to the server to which it was connected; the utuser command had to be invoked from that server. Beginning with SRSS 3.1, however, you can access the token card reader by invoking utuser -r from any server in the relevant failover group. The procedure otherwise remains as it was in earlier releases.

single-step bullet  Type the following command:

# /opt/SUNWut/sbin/utuser -r Token Reader

where Token Reader is the MAC address of the DTU containing the smart card whose ID you want to read. Insert the smart card into the DTU and run the utuser command. This command queries the DTU for the smart card token’s ID and, if successful, displays it. For example:

# /opt/SUNWut/sbin/utuser -r 08002086e18f
Insert token into token reader ’08002086e18f’ and press return.
Read token ID ’mondex.9998007668077709’

Using the utcapture Tool

The utcapture tool connects to the Authentication Manager and collects data about the packets sent and packets dropped between the Sun Ray server and the DTU. The data in TABLE 2-4 is then displayed on the screen in the following format:

TABLE 2-4 Data Elements Displayed

Data Element



The MAC address of the DTU


The time the loss occurred in year-month-day-hour-minute-second format.
Example: 20041229112512


Total number of packets sent from server to DTU


Total number of packets reported as lost by DTU


Total number of bytes sent from server to DTU


Percentage of packets lost between the current and previous polling interval


Time in milliseconds for a round trip from DTU to server.

Tip - If Sun Ray DTU traffic loss is more than .1%, allocate higher priority to the VLAN that carries Sun Ray DTU traffic. For more information on how to change the priority, please refer to the manufacturer’s documentation for your switch.

The following utcapture options are supported:

TABLE 2-5 utcapture Options




Help for using the command.


Dump output to stdout in raw format. By default, data is dumped when there is a packet loss. With this option, the data is always dumped to stdout

-s server

Name of server on which the Authentication Manager is running. By default, it is the same host that is running utcapture.

-i filename

Process raw data from a file specified by file name and dump to stdout only the data for those DTUs that had packet loss.


Collects the data for the specified DTUs only. DTUs are specified on the command line by their desktop IDs separated by a space. By default, data for all currently active desktops is collected.

procedure icon  To Start utcapture

From a command line, enter one of the following commands:

% /opt/SUNWut/sbin/utcapture -h

This command lists the help commands for the utcapture tool.

% /opt/SUNWut/sbin/utcapture

This command captures data every 15 seconds from the Authentication Manager running on the local host and then writes it to stdout if there is any change in packet loss for a DTU.

% /opt/SUNWut/sbin/utcapture -r > raw.out

This command captures data every 15 seconds from the Authentication Manager running on the local host and then writes it to stdout.

% /opt/SUNWut/sbin/utcapture -s sunray_server5118.eng \ 080020a893cb 080020b34231

This command captures data every 15 seconds from the Authentication Manager running on server5118.eng and then writes the output to stdout if there is any change in packet loss for the DTU with ID 080020a893cb or 080020b34231.

% /opt/SUNWut/sbin/utcapture -i raw-out.txt

This command processes the raw data from the input file raw-out.txt and then writes to stdout the data only for those DTUs that had packet loss.

Examining Log Files

Significant activity concerning files retrieved from the Sun Ray server is logged and saved. The server stores this information in text files. TABLE 2-6 describes the log files that are maintained.

TABLE 2-6 Log Files

Log File





Lists operations performed during server administration. This log is updated daily. Archived files are stored on the system for up to one week and are annotated using numeric extensions (for example, from file name admin_log.0 to admin_log.5).



Lists events logged from the Authentication Manager. The auth_log file is updated (up to a limit of 10) every time the server’s authentication policy is changed or started. The archived authentication files are annotated using numeric extensions (for example, from auth_log.0 to auth_log.9).

Automatic Mounting


Lists mount messages for mass storage devices. The archived mountd files are annotated using numeric extensions (for example, from utmountd.log.0 to utmountd.log.9).

Mass Storage Devices


Lists mass storage device events. The archived storage files are annotated using numeric extensions (for example, from utstoraged.log.0 to utstoraged.log.9).



Lists events from the server’s DTUs, including details of registering, inserting, or removing smart cards. This file is updated daily. Archived files are stored on the server for one week annotated with numeric extensions (for example, from messages.0 to messages.5).

Web Admininstation


Lists web administration-related messages. The archived log files are annotated with numeric extensions.