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

1.      Kiosk Session Service JDS3 Session
1.1     Session Descriptor
1.2     Session Script
1.3     Configuring the session
1.3.1   Session script arguments
1.3.2   Session gconf data


1. Kiosk Session Service JDS3 Session
-------------------------------------
This product provides support for JDS3 sessions in Kiosk Mode. The core
components of this product are a Kiosk Session Service session descriptor 
(/etc/opt/SUNWkio/sessions/jds3.conf) and a Kiosk Session Service session
script (/etc/opt/SUNWkio/sessions/jds3/jds3-kiosk-session). This session
supports added applications and a number of sample applications are included.

Without any additional configuration, the session provided is a minimal JDS3
session with available lockdown capabilities enabled. The following attributes
apply:
    - The desktop background is solid black.
    - Nautilus "show desktop" is disabled i.e. no desktop menu and no desktop
      launchers are visible.
    - The only available element on the desktop is a panel.
    - The panel is empty, except for a single main menu, and locked down i.e.
      the panel cannot be modified in any way by the user.
    - The main menu contains an empty Applications submenu and an "Exit Session"
      button.
    - Clicking the Exit Session button results in the JDS3 session exiting
      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.

1.2 Session Script
------------------
The session script is responsible for launching the JDS3 session. The
script provides a simple wrapper on the gnome-session executable. Before
starting gnome-session, the script completes the following tasks:

 . load all available gconf data files (See Section 1.3.2 for details).
   These are used to enable lockdown, configure the panel etc.
 . configure nautilus such that it doesn't launch the "About Gnome"
   application and doesn't add default launchers to the desktop
 . set the desktop background if configured (See Section 1.3.1 for details)
 . add any configured Kiosk Mode applications

1.3 Configuring the session
---------------------------
The session may be configured using session script arguments and/or by
modification to gconf data loaded during session startup.

1.3.1 Session script arguments
------------------------------
The session supports the following session script arguments:
 -b <background>
     indicates that the session should use <background> as the desktop
     background instead of the default "solid black" background. The background
     to be used is configured by setting the values of a number of gconf
     entries.  Valid formats for <background> (and associated gconf entries)
     are as follows:

     [<mode>:]<picture_file_path>
      <mode> corresponds to the gconf entry
      /desktop/gnome/background/picture_options. Valid values are "wallpaper",
      "scaled" etc.
      <picture_file_path> corresponds to the gconf entry
      /desktop/gnome/background/picture_filename and indicates the absolute
      path to an image file to be used as the desktop background.

     <colour>
      <colour> corresponds to the gconf entry
      /desktop/gnome/background/primary_color. Valid values are colour names
      e.g. "red" or colour specifications e.g. "#D51A1A".

 -s
     indicates that nautilus should "show the desktop". This directs nautilus
     to show any available desktop launchers and to provide a desktop menu.
     This behaviour is achieved by setting the value of the gconf entry
     /apps/nautilus/preferences/show_desktop to true.  The default behaviour of
     the session is that nautilus will not show the desktop.

     Note: use of the -s option can diminish the effectiveness of the lockdown
           facility. 

1.3.2 Session gconf data
------------------------
The session script loads (via gconftool-2 --load) the contents of all gconf
data files, with a .xml suffix, found in $KIOSK_SESSION_DIR/jds3/gconfdata.
A number of gconf data files are included with the session by default. The
settings in these files are used to enable lockdown, configure the panel etc.
You may further configure the session by adding your own gconf data files in
the gconfdata directory.
