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

Command

Definition

utaction

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

utadm

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

utadminuser

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.

utamghadm

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

utcapture

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.

utcard

The utcard command allows configuration of different types of smart cards in the Sun Ray Data Store

utconfig

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

utcrypto

The utcrypto command is a utility for security configuration.

utdesktop

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

utdetach

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 again only after authentication. When Remote Hotdesk Authentication (RHA) is disabled (via utpolicy or the Admin GUI), utdetach affects only authenticated smart card sessions and non-smart card mobile sessions.

utdevadm

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.

utdiskadm

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

utdssync

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.

uteject

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

utfwadm

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

utfwload

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

utfwsync

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.

utgmtarget

The utgmtarget command manages a group-wide list of explicit destinations for Sun Ray group membership announcements.

utgroupsig

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.

utgstatus

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.

utinstall

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.

utkiosk

The utkiosk tool is used to import/export kiosk configuration information into the data store. It also supports storage of multiple named kiosk session configurations in the data store.

utkioskoverride

The utkioskoverride command provides a way to set the session type associated with a token, to select a kiosk session configuration for a token associated with a kiosk session, or to query the session type and kiosk session currently associated with a token.

utmhadm

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.

utmhconfig

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

utmount

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

utpolicy

The utpolicy command sets and reports the policy configuration of the Sun Ray Authentication Manager, utauthd(1M).

utpreserve

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

utpw

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.

utquery

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

utreader

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

utreplica

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.

utresadm

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.

utresdef

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.

utrestart

The utrestart command is used to start Sun Ray services.

utselect

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.

utsession

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

utset

Use utset to view and change Sun Ray DTU settings.

utsettings

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.

utswitch

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.

utumount

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

utuser

The administer can manage Sun Ray user tokens registered on a Sun Ray server by running the utuser command on it. The utuser command also provides information on the currently inserted token (smart card) for a specified DTU that is configured as a token reader.

utwall

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

utwho

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

utxconfig

The utxconfig program provides Xserver 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:


# utrestart

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

Or

single-step bullet  Type:


# 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:


% 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:


% 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:


% 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:


% 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

Field

Description

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:

mondex.9998007668077709
pseudo.080020861234

Server Name

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

Server Port

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

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

Setting an authentication policy with utpolicy, automatically sets the failover group policy, so all you need to do after making a policy change is to reset or restart services. You can also modify policy settings with the Admin GUI System Policy tab (see FIGURE 3-12).


TABLE 2-3 utrestart Commands

Command/Option

Result

utrestart

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.

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

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


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 Admin 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.1 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}

where


username

=

User’s Unix ID

hostname

=

Host on which the command is executed

service

=

Name of the service being executed

cmd

=

Name of the command being executed

message

=

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 Advanced tab (see FIGURE 3-11).

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:


# 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:


# utdevadm -e -s usb


procedure icon  To Disable USB Service

single-step bullet  Use the utdevadm command as below:


# utdevadm -d -s usb


procedure icon  To Perform a Warm Restart

single-step bullet  Use the utrestart command as below:


# utrestart


procedure icon  To Perform a Cold Restart

single-step bullet  Use the utrestart command with the -c option as below:


# utrestart -c



Note - Be sure to notify your users before performing a cold restart, which terminates all existing sessions on a server. To restart Sun Ray services without terminating sessions, perform a warm restart.



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 Configure a Private Sun Ray Network

single-step bullet  To add an interface, type:


# 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 192.168.128.0 and 192.168.254.0.



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 Configure a Second Private Sun Ray Network

single-step bullet  To add another interface, type, for example:


# utadm -a hme1


procedure icon  To Delete an Interface

single-step bullet  Type:


# 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:


# 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:


# utadm -A subnet_number


procedure icon  To Delete a LAN Subnet

single-step bullet  Type:


# utadm -D subnet_number


procedure icon  To List the Current Network Configuration

single-step bullet  Type:


# utadm -l

utadm -l lists all the currently configured networks.


procedure icon  To Remove All Interfaces and Subnets

Use the utadm -r command to remove all entries and structures relating to Sun Ray interfaces and subnets.

single-step bullet  Type:


# utadm -r


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.



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. 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:


# 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:


# 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:


# utrestart


Smart Card Configuration Files

Use the Admin GUI 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 Admin GUI.


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.

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

When you enable an authentication policy with registered users, or token owners, be sure to specify smart card IDs for them. To utilize token readers with regional hotdesking based on Sun Ray pseudo-tokens, use the Site-specific Mapping Library to produce the desired behavior for them. See To Configure a Site-specific Mapping Library and Token Readers with Regional Hotdesking.

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


Token Reader Icon

When a site policy disallows pseudo-sessions, DTUs configured as token readers display the token reader icon instead of the Login Dialog box. The token reader is also called the card reader. (See Token Reader Icons.)

FIGURE 2-3 Token Reader (Card Reader) Icon


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


procedure icon  To Configure a Token Reader

The utreader command allows a DTU to be used as a token reader, for registering smart cards. When a DTU is configured as a token reader, inserting or removing a smart card does not initiate session mobility; any session connected to that DTU remains connected to it regardless of card movement events.

Token reader mode is useful when you want to determine the raw token ID of a smart card.

single-step bullet  For instance, to configure the DTU with MAC address 0800204c121c as a token reader, type the following command:


# utreader -a 0800204c121c

single-step bullet  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:


# utreader -d 0800204c121c

single-step bullet  To unconfigure all token readers on this server:


# 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. Now, 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:


# 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

Description

TERMINALID

The MAC address of the DTU

TIMESTAMP

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

TOTAL PACKET

Total number of packets sent from server to DTU

TOTAL LOSS

Total number of packets reported as lost by DTU

BYTES SENT

Total number of bytes sent from server to DTU

PERCENT LOSS

Percentage of packets lost between the current and previous polling interval

LATENCY

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




Tip - Sun Ray DTU traffic loss of more than 0.1%, may indicate a network problem. You may want to allocate higher priority to the VLAN that carries Sun Ray DTU traffic. For more information on how to change the priority, see the manufacturer’s documentation for your switch.


The following utcapture options are supported:


TABLE 2-5 utcapture Options

Option

Definition

-h

Help for using the command.

-r

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.

desktopID

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

single-step bullet  From a command line, enter one of the following commands:


% utcapture -h

This command lists the help commands for the utcapture tool.


% 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.


% 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.


% 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.


% 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

Path

Description

Administration

/var/opt/SUNWut/log/admin_log

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).

Authentication

/var/opt/SUNWut/log/auth_log

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

/var/opt/SUNWut/log/utmountd.log

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

/var/opt/SUNWut/log/utstoraged.log

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

Messages

/var/opt/SUNWut/log/messages

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 up to seven days or 3.5 MB, annotated with numeric extensions (for example, from messages.0 to messages.5).

Web Administration

/var/opt/SUNWut/log/utwebadmin.log

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