#
# ident "README $Rev: 5385 $ $Date: 2009-11-20 01:55:56 -0800 (Fri, 20 Nov 2009) $ SMI"
#
#*******************************************************************************
#
# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#*******************************************************************************
#

1.      Sun Ray Connector for Windows OS Kiosk Session
1.1     Session Descriptor
1.2     Session Script
1.3     Session Script Arguments
1.3.1   Non Sun Ray Connector arguments
1.3.2   Sun Ray Connector arguments
2.      Supplemental Information
2.1     Follow-me-printing
2.2     Windows Session Locking


1. Sun Ray Connector for Windows OS Kiosk Session
-----------------------------------------------------------------
This product provides support for Sun Ray Connector sessions in Kiosk Mode. The
core components of this product are a Kiosk Session Service session descriptor 
(/etc/opt/SUNWkio/sessions/uttsc.conf) and a Kiosk Session Service session
script (/etc/opt/SUNWkio/sessions/uttsc/uttsc). This session does not support
added applications.

1.1 Session Descriptor
----------------------
The session descriptor defines a number of attributes useful for the
administration and launching of the session. These include

 KIOSK_SESSION_EXEC
 identifies the location of the session script.

 KIOSK_SESSION_LABEL and KIOSK_SESSION_DESCRIPTION
 identify a label and description respectively to be used by the Sun Ray
 administration console.

 KIOSK_SESSION_ARGS
 identifies default session script arguments. For more details, see the
 "Session Script Arguments" section below.

1.2 Session Script
------------------
The session script is responsible for launching the Sun Ray Connector. The
script provides a simple wrapper on the Sun Ray Connector executable,
/opt/SUNWuttsc/bin/uttsc.

A two minute timeout is imposed on Windows sessions which remain at the Windows
login screen. When this timeout elapses, the associated Windows session is
terminated and the Sun Ray Connector also subsequently terminates. This can
result in a user experience where, assuming no Windows login takes place, a
desktop unit appears to reset every two minutes. To avoid this, the session
script supports its own timeout which affects its behaviour when it detects that
the Sun Ray Connector has terminated. If the timeout has not elapsed, the
session script will relaunch the Sun Ray Connector. If the timeout has elapsed,
the session script will terminate and the Kiosk session will also terminate as a
result. The timeout may be specified as a session script argument and has a
default value of 30 minutes.

The session script requires that the KIOSK_SESSION_DIR argument is correctly
set to point to the directory holding the script and other session components.

1.3 Session Script Arguments
----------------------------
A number of arguments are supported by the session script. These may be
specified using the Sun Ray administration console. The list of supported
arguments may be split into Sun Ray Connector and non Sun Ray Connector
arguments. Sun Ray Connector arguments are not processed in any way by the
session script and are simply passed directly to the Sun Ray Connector. Non Sun
Ray Connector arguments are processed by the session script itself.
The complete argument list should be formatted according to

 [<Non Sun Ray Connector arguments>] [ "--" <Sun Ray Connector arguments>]

1.3.1 Non Sun Ray Connector arguments
-------------------------------------
 
The following arguments are processed by the session script directly:

 -h           allow showing the menu pulldown header in uttsc. Without this
              option, the "-b" option will always be used when invoking uttsc.

              You can still specify the "-b" Sun Ray Connector option
              explicitly, even if the "-h" non Sun Ray Connector argument is
              specified. The "-h" argument merely prevents that the "-b" option
              is applied automatically.

 -t <timeout> sets the value of a timeout (in seconds) after which
              the session script will terminate in the event of a Sun Ray
              Connector termination. If Sun Ray Connector terminates before
              the timeout has elapsed, it will be restarted by the session
              script.
              The default value for <timeout> is 1800 ( 30 minutes ).
              Values less than or equal to 0 indicate that the session script
              should never restart the Sun Ray Connector.

1.3.2 Sun Ray Connector arguments
---------------------------------
You may specify any valid uttsc(1) arguments here that are compatible with
fullscreen mode. The "-m" option is always used automatically, so that the
Sun Ray Windows Connector always runs in fullscreen mode. The "-b" option is
automatically used to disable the fullscreen menu pulldown header, unless the
"-h" non Sun Ray Connector argument is used.

Note: The Sun Ray Connector requires that at least a "server" argument is
      provided. As previously mentioned, you may use the Sun Ray administration
      console to include this server argument in the session script argument
      list.

2. Supplemental Information
---------------------------
We are aware of two features linked to Sun Ray Connector which are commonly
implemented at customer sites. These are Follow-me-printing and Windows Session
Locking. Implementations of these features rely on technology not available by
default and non public Sun Ray interfaces as well as the use of certain public
Sun Ray interfaces for purposes other their intended use. For these reasons
we cannot provide these features as supported elements of this session. We
do, however, provide descriptions of how these features are commonly implemented
in the following sections.

2.1 Follow-me-printing
----------------------
This feature is used to allow the default printer for a given Windows session
"move" with a user as he moves from one Sun Ray to another. The following
steps are taken to provide this feature.

For each Sun Ray of interest, an associated printer is specified in the Sun Ray
Datastore. This may be done by navigating to the relevant Desktop Unit in the
Sun Ray administration console and setting its "Other Information" field to
the name of the relevant printer.

The next step is to provide a shell script which queries the printer name
stored in the Sun Ray Datastore for the current Sun Ray and writes that name
to the user's $HOME/.printers file. For example

#!/bin/sh
if [ `uname` = Linux ] ; then
 theFlag="-P"
fi
theMACAddr=`cd $theFlag $UTDEVROOT ; /bin/pwd | sed 's/.*\(............\)/\1/'`
thePrinter=`/opt/SUNWut/sbin/utdesktop -o |
            grep $theMACAddr           |
            /usr/bin/awk -F, '{print $3}'`
echo "_default $thePrinter" > $HOME/.printers

The next step is to use utaction(1) to invoke the script above on an initial
connection and subsequently whenever a user moves from one Sun Ray to another.
This can be done by providing an Xsession.d script if you are using dtlogin as
your login manager or an xinitrc.d script if you are using gdm as your login
manager. For example, you might create the script
/usr/dt/config/Xsession.d/1100.SUNWut for dtlogin or
/etc/X11/xinit/xinitrc.d/1100.SUNWut for gdm as follows

#!/bin/sh
/opt/SUNWut/bin/utaction -i -c <path-to-script> &

where <path-to-script> is the path to the script you created to retrieve the
printer name.

Note: The name 1100.SUNWut is chosen purposely in this case to ensure that
      the script is run or sourced after the existing script 0100.SUNWut.
      This is required as 0100.SUNWut is responsible for setting $UTDEVROOT
      which is needed by the first sample script above.

The final step is to modify your Kiosk session script arguments to "forward" the
printer to Windows. You may modify these arguments using the Sun Ray
administration console. In this example you would need to add the argument
"-r printer:_default" to the existing arguments. This would result in an
argument list similar to the following

-t 1800 -- -r printer:_default myHost

where "myHost" corresponds to the server argument passed to uttsc(1).

2.2 Windows Session Locking
---------------------------
It may be preferrable that a Windows session be locked when a user's session
moves away from a given Sun Ray. A commonly used approach to implement this is
to send the lockscreen keystrokes to the Windows Session using xvkbd ( invoked
by utaction ). 

As with the previous example you may invoke utaction from an Xsession.d or
xinitrc.d script as follows.

#!/bin/sh
XVKBD=/usr/openwin/bin/xvkdb
/opt/SUNWut/bin/utaction  -d "$XVKBD -text '\Ml'" &

Note: xvkbd is not available by default so you should modify the XVKBD setting
      above so that it correctly identifies the installation location of
      xvkbd in your case.

Note: the keystroke sequence '\Ml' will activate the Windows lock for
      Windows 2003/XP sessions. You may need to modify the sequence for other
      Windows versions.
