#
# ident "@(#) $Id$ SMI"
#
#*******************************************************************************
#
# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#*******************************************************************************
#

1.      Kiosk Session Service CDE Session
1.1     Session Descriptor
1.2     Session Script
1.3     Configuring the session
1.3.1   Session script arguments
1.3.2   Session prototype
2.      Controlled Access Mode Compatibility
2.1     No-dtsession mode.
2.2     Known Incompatibities


1. Kiosk Session Service CDE Session
-------------------------------------
This product provides support for Common Desktop Environment (CDE) sessions 
in Kiosk Mode. The core components of this product are a Kiosk Session Service 
session descriptor (/etc/opt/SUNWkio/sessions/cde.conf) and a Kiosk session
script (/etc/opt/SUNWkio/sessions/cde/cde-kiosk-session). This session
supports added applications.

This product is intended to provide an environment that can serve as a 
replacement for the "Controlled Access Mode" (CAM) environment that was 
available as part of Sun Ray Server Software up to version 3.1.

Without any additional configuration, the session provided is a minimal CDE
session with the following attributes:
    - Empty workspace with a dark background.
    - No front panel.
    - The only available control is a workspace (right click) menu, with the 
      following items:
      - "Kiosk Menu" (menu title)
      - "Refresh" (Refresh workspace action)
      - "Exit Session" (Exit Session Action)
      The actual menu item text may vary depending on the session locale.
    - Selecting "Exit Session" exits the session without a prompt.

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 the label and description respectively to be used by the Sun Ray
 administration console.

 KIOSK_SESSION_PROTOTYPE
 identifies the session prototype directory which will be copied to Kiosk users'
 home directories during session startup.

See the kiosk(5) man page for documentation about Kiosk session descriptors.

1.2 Session Script
------------------
The session script is responsible for launching the CDE session. It takes the 
role of the Xsession script in regular sessions. It sets up the environment 
and starts the dtsession(1) Session Manager executable. Before starting 
dtsession, the script completes the following tasks:

 - add configured Kiosk applications
   - Applications configured with the 'user' or 'auto' modes, are added to the 
     workspace menu.
   - Applications configured with the 'auto' or 'critical' modes are 
     automatically launched when the session starts. If a 'critical' application
     exits, the session is terminated.
 - prepare the session environment
   - set desktop search paths - see dtsearchpath(1)
   - start Tooltalk           - see ttsession(1)

The script does not perform the following tasks, which are performed during 
startup of non-Kiosk CDE sessions: 
   - run dtappgather(1) to gather Application Manager applications
   - run dtdbcache to speed up applications that use CDE actions
   - run dsdm(1X) to enable Drag and Drop between OPENLOOK and Motif windows.
If you require any of these features, please add them to your custom Kiosk 
application script.

See the kiosk(5) man page for documentation about Kiosk session scripts and 
Kiosk applications.

1.3 Configuring the session
---------------------------
The session may be configured using session script arguments and/or by
adding configuration files to the session prototype. 

1.3.1 Session script arguments
------------------------------
The session supports the following session script arguments:
 -no-dtsession
     indicates that the session should run in no-dtsession CAM compatibility
     mode. 
     
     This argument is DEPRECATED and may be removed in a future release of 
     this product. It is intended solely for use in automatically migrated CAM 
     configurations. Do not use this argument in new custom configurations. 
     Create a custom session instead.

See the session.conf(4) man page for documentation about session arguments.
See the kiosk(5) man page for documentation about creating custom Kiosk sessions.
See the utcammigrate(1M) man page for documentation about migrating CAM 
configurations.

1.3.2 Session prototype
------------------------
You can add files to define CDE desktop resources and configuration.
The session script loads resources from a .Xdefault file, if available in the 
session prototype.

See the kiosk(5) man page for documentation about Kiosk session prototypes.

2. Controlled Access Mode Compatibility
----------------------------------------
In a Sun Ray Kiosk Mode environment the Kiosk Session Service CDE session can 
serve as a replacement for the Controlled Access Mode (CAM) environment, which 
was available in Sun Ray Server Software 2.x and 3.x.

The environment was designed to be similar and compatible to the environment 
provided by CAM. The utcammigrate(1M) tool supports creating Kiosk Mode 
configurations from existing CAM configurations.

The CDE Kiosk Session has the invocation of dtsession(1) built in. A separate 
application descriptor for dtsession should not be used with this session.

In CAM, dtsession was available as a preconfigured application, which could be 
removed from the configuration, if a session without window manager (or with 
a different window manager) was desired. If such a configuration is migrated, 
utcammigrate adds the -no-dtsession session argument to the migrated 
configuration, so that the session runs in no-dtsession mode.

2.1 No-dtsession mode
----------------------
Note: no-dtsession mode is supported only for use by migrated CAM 
configurations. Do not use this feature for new configurations.

In no-dtsession mode the CDE Session Manager dtsession(1) and Window Manager 
dtwm(1) are not started by the Kiosk Session script and CDE-specific session 
preparation is omitted.

The following features of the CDE Kiosk Session script are deactivated in 
no-dtsession mode:
- No CDE workspace is displayed
- No CDE-specific set up is executed. Tooltalk is not started and 
  dtsearchpath(1) is not run.
- No workspace menu is available, a workspace menu definition (dtwmrc) is not
  generated. As a result Kiosk applications with start mode 'user' will not 
  be available to the session.

At least one 'critical' application must be defined when no-dtsession mode is 
used. 

2.2 Known Incompatibities
--------------------------
If your custom CAM solution relies on one of the following behaviors, features 
and attributes of CAM, it will cease to work properly in the Kiosk environment:

- Sourced 'wrapper' scripts
  CAM supports creating 'wrapper' scripts in the special directory 
  /opt/SUNWut/kiosk/wrappers. Such wrapper scripts are sourced by CAM in 
  an unspecified shell script context and must perform some undocumented 
  steps to launch an application.
  Neither Kiosk Mode nor the Kiosk CDE Session support sourcing application 
  scripts in a shell script context or provide an emulation of the CAM 
  wrapper environment.

- CAM command-line tools, except utkiosk(1M).
- Locations, names or contents of CAM configuration files  
- Location of CAM prototype directories
- Location of CAM user account home directories
- Identification of a given user account as a kiosk user account
- Availability of a partial clone of system directories, originally intended 
  to serve as chroot(1M) environment
- CAM-specific environment variables, generally having the form $BB*  
- Other undocumented properties of the CAM environment 

