dtsession Command

Purpose

Manages a CDE session.

Syntax

dtsession [options] ...

Description

The dtsession command provides session management functionality, compliant with ICCCM 1.1, during a user's session, from login to logout. It launches a window manager and allows users to save a session, restore a session, lock a session, launch screen savers, and allocate colors for desktop-compatible clients.

Note: The desktop login manager dtlogin automatically invokes the dtsession client through the Xsession script. The dtsession client can also be started through the Xsession script on an existing X server. The dtsession session manager automatically starts a window manager.

The dtsession command supports the following tasks:

Initializing a session
Launching a window manager
Restoring a home or current session
Providing session locking on command or timeout
Providing session screen saving on command or timeout
Acting as a color allocation server for other desktop clients
Saving a home or current session
Displaying confirmation dialog at logout
Displaying session selection dialog at logout
Terminating a session

Sessions

A session is the collection of applications, settings and resources that are present on the user's desktop. Session management is a set of conventions and protocols that allow a special session manager, such as dtsession, to save and restore a user's session. A user can log in to a system and be presented with the same set of running applications, settings, and resources that were present when the user logged off. When a user logs in to the desktop for the first time, a default initial session is loaded. Afterward, dtsession supports the notion of a current and a home session.

The following sessions are defined:

Initial Session: When a user logs in to the desktop for the first time, dtsession generates the user's initial session using system default values. Refer to Session Resource Management and Session Application Management for more information.
Current Session: The user's session that is running is always considered the current session, whether restored upon login from a saved home session, a saved current session, or the system default initial session. Based on the user's Style Manager Startup settings, when the user exits the session, the current session is automatically saved. When the user next logs in to the desktop, the previously saved current session is restarted. The desktop is restored to the same state it was in when the user last logged out.
Home Session: Another option restores the desktop to the same state every time the user logs in, regardless of its state when the user logged out. The user can save the state of the current session, then sets the Style Manager Startup so that the desktop starts that session every time the user logs in.
Display-Specific Sessions: To run a specific session for a specific display, users can create a display-specific session. To do this, users can copy the $HOME/.dt/sessions directory to $HOME/.dt/display, where display is the real, unqualified host name (for example, pablo:0 is valid, but pablo.gato.com:0 or local:0 is not). When the user logs in on display pablo:0, that display-specific session takes precedence.

ICCCM Session Management Protocol

For an application to be saved upon logout and restarted upon login, it must participate in a simple session management protocol. The dtsession command supports the ICCCM 1.1 Session Management Protocol.

Applications that want to save their state can take part in the WM_SAVE_YOURSELF protocol. To do this, an application needs to set the WM_SAVE_YOURSELF property on one and only one of its top-level windows. When a session is saved, dtsession sends the application's top-level window a WM_SAVE_YOURSELF client message. At this point, the application proceeds to quietly save its state. The application cannot interact with the user in any way while it is saving its state. Because an application will likely save its state into a file, the session manager provides a convenience function, DtSessionSavePath, which returns a full path name of a file in which an application can save its state. While the application is saving its state, dtsession awaits notice from the application that it is finished. In order to tell dtsession that the state save is complete, the application must update the WM_COMMAND property on its top-level window.

The WM_COMMAND property on an application's top-level window serves two purposes. First, a change of this property indicates to dtsession that an application is finished saving its state and dtsession can proceed to the next application. Second, the WM_COMMAND property value is expected to contain the command line that dtsession uses to restart the application at session startup. If an application is launched with a full path name, it should use the full path name when setting WM_COMMAND. Applications that do not need to save their state but want to be restarted can simply set WM_COMMAND once during application startup.

Restoring a Session

At session startup time, dtsession determines which session to restore. The following list describes the order of precedence:

Display-specific Current of Home Session
Current or Home Session
Initial Session

Session Resource Management

The session manager uses the X Server RESOURCE_MANAGER property on which to make available desktop resources to all applications. The session manager loads the RESOURCE_MANAGER in the following manner:

Loads the system default resources.
Merges any system administrator-specified resources.
Merges any user-specified resources.

The desktop default resources can be found in the /usr/dt/config/$LANG/sys.resources file. These resources are made available to each user's session through the RESOURCE_MANAGER property. Do not edit this file because it is unconditionally overwritten during subsequent desktop installations.

By creating a /etc/dt/config/$LANG/sys.resources file, a system administrator can override system default resources or specify additional resources. Because this file is merged into the desktop default resources during session startup, only new or updated resource specifications should be placed in this file. This is preferable to making a copy of the desktop default resource file. Resources specified in this file are made available to each user's session through the RESOURCE_MANAGER property. Resources specified in this file take precedence over those specified in the desktop default resource file.

By editing the $HOME/.Xdefaults file, a user can override the desktop default and system administrator resources. Resources specified in this file are made available to only that user's session through the RESOURCE_MANAGER property and take precedence over those resources specified in the desktop default or system administrator resource files.

Note: The X Toolkit Intrinsics specifies that it will load application resources from either RESOURCE_MANAGER or from $HOME/.Xdefaults, but not both. Ordinarily, this means that the user's $HOME/.Xdefaults file would be ignored. However, the session manager accommodates $HOME/.Xdefaults by merging it into the RESOURCE_MANAGER at session startup, as previously described. When users change their $HOME/.Xdefaults files, their changes are not visible to new applications until the users invoke the ReloadResources action.

The ReloadResources action instructs the session manager to reload the RESOURCE_MANAGER with the system-specified, system administrator-specified,, and user-specified resources. This makes available to new applications changes that were made to system administrator-specified or user-specified resource files.

Session Application Management

At session startup, the session manager restarts any applications that were saved as part of the session. The system default set of applications to be restored as part of the user's Initial Session can be found in the /usr/dt/config/$LANG/sys.session file. Do not edit this file because it is unconditionally overwritten during subsequent desktop installations.

A system administrator can replace the set of applications that are restored as part of the user's Initial Session by creating a /etc/dt/config/$LANG/sys.session file. Unlike the resource files, this file is used as a complete replacement for the desktop default file, so you can make a copy of the system default file and make any necessary modifications.

The Window Manager

The dtsession command starts the window manager. By default, /usr/dt/bin/dtwm is started. An alternate window manager can be specified using the wmStartupCommand resource. Refer to the Workspace Manager specification for more information.

The Style Manager

The style manager provides the interface by which a user can change various desktop and X server settings for the current session. Refer to the Style Manager specification for more information.

The Color Server

The dtsession command serves as the color server for the desktop and provides the following set of resources that can be used to configure it:

foregroundColor: Controls whether a pixel is allocated for the foreground color.
dynamicColor: Specifies whether read-only colors are allocated.
shadowPixmaps: Specifies whether colors are allocated for top shadow or bottom shadow.
colorUse: Limits color allocation.
writeXrdbColors: Specifies whether the *background and *foreground resources are placed in the resource database.

See the Color Server Resources section for more information.

Session Lock

The dtsession command provides session locking. The current session can be locked directly by pressing the lock icon on the front panel. If supported by the X server, the current session can be locked after a specified period of inactivity. To unlock the session, users must enter their login password, the login password for the root user, or the login password for any of the users specified by the keys resource. See Screen Lock and Screen Save Resources for more information on the keys resource.

The dtsession command is a PAM-enabled session manager with service name dtsession. It supports traditional local UNIX authentication as well as PAM authentication for unlocking the session. Additional reauthentication functionality, such as that required by DCE, can be added by individual vendors.

System-wide configuration to use PAM for authentication is set by establishing root user permissions and modifying the value of the auth_type attribute in the usw stanza of the /etc/security/login.cfg file to PAM_AUTH.

The authentication mechanisms used when PAM is enabled depend on the configuration for the login service in /etc/pam.conf. The dtsession command requires an /etc/pam.conf entry for the auth module type. The following configuration is recommended in /etc/pam.conf for the dtsession service:

  dtsession        auth               required       /usr/lib/security/pam_aix

Screen Savers

The dtsession command provides support for the launching of external screen savers as a part of session locking from the front panel or, if supported by the X server, after a specified period of inactivity. Refer to the Screen Saver specification for information as to how screen savers are integrated into the desktop.

X Server Screen Saver Extensions

The dtsession command's ability to provide session lock or screen saver launch after a specified period of inactivity depends upon the availability of an X server screen saver extension. The dtsession command supports the X Consortium Sample X11 Screen Saver Extension 1.0 and the HP X Screen Saver Extension. The ability of the dtsession command to recognize both, either, or none of these extensions is vendor specific.

Launching the Session Manager

The dtsession command should be launched from the Xsession script. Xsession is described in the login manager specification. Although launching Xsession from dtlogin as part of the default login sequence is recommended, some systems allow proxy programs, such as xinit, x11start, or startx, to start Xsession.

Color Server Resources

Item	Description

colorUse	ClassClass: ColorUse Type: String Default: DEFAULT Description: Specifies the number of colors to use for the user interface. Color server will determine type of monitor based upon number of display planes of the screen as follows: 1,2 or 3 planes (B_W) Specifies a black-and-white system. The color palettes use two color cells for the user interface. In this configuration, only two color palettes are available: BlackWhite and WhiteBlack. These palettes cannot dynamically change. To change a palette, all applications using that color palette must be restarted. This resource value forces ShadowPixmaps to True, and ForegroundColor to either black or white (depending on the palette chosen). 4 or 5 planes (LOW_COLOR) Specifies a low-color system. The color palettes have two color sets and use a maximum of 12 color cells for the user interface, including black and white (color cells 0 and 1). The number of color cells can be reduced by using the resources ShadowPixmaps and ForegroundColor. 6 planes (MEDIUM_COLOR) Specifies a medium-color system. The color palettes have four color sets and use a maximum of 22 color cells for the user interface, including black and white (color cells 0 and 1). The number of color cells can be reduced by using the resources ShadowPixmaps and ForegroundColor. 7+ planes (HIGH_COLOR) Specifies a high-color system. The color palettes have eight color sets and use a maximum of 42 color cells for the user interface, including black and white (color cells 0 and 1). The number of color cells can be reduced by using the resources ShadowPixmaps and ForegroundColor.
dynamicColor	ClassClass: DynamicColor Type: Boolean Default: True Description: This resource can have values of True or False. The dynamicColor resource is used to reduce the number of color cells being used. After a palette has been selected and it is not likely to be changed, dynamicColor can be set to False. If set to False, colors cannot be dynamically changed using the desktop style manager. A selected palette takes effect the next session. The next time the session comes up, the color server uses Read Only color cells that can be shared by all clients, reducing the number of color cells used.
foregroundColor	ClassClass: ForegroundColor Type: String Default: DYNAMIC Description: This resource can have values of White, Black, or Dynamic. The foregroundColor resource causes all text (foreground) to use either pixel 0 or 1 (Black or White) or to have a color cell dedicated to foreground and changes in response to the background color (Dynamic) for each ColorSet. If set to White or Black, the number of color cells used per ColorSet is reduced by 1.
shadowPixmaps	ClassClass: ShadowPixmaps Type: String Default: DEFAULT Description: For color systems, this resource can have a value of True or False. If True, topShadowColor and bottomShadowColor use the same pixel as background and topShadowPixmap and bottomShadowPixmap are specified instead of solid color to create the 3-D look. This reduces the number of color cells per ColorSet by 2. This resource defaults to True for systems with four or less color planes (16 or less color cells), and False for systems with more than four color planes.
writeXrdbColors	ClassClass: WriteXrdbColors Type: Boolean Default: True

Screen Lock and Screen Save Resources

Item	Description

keys	ClassClass: Keys Type: unsigned char Default: NULL Description: Lists key holders who have the ability to unlock the screen any time it is locked by the user. The list is a list of user IDs separated by commas. For example, if user `kim` has the following resource active during a session, users `fred` and `keith` have the ability to unlock the display when `kim` locks it: `Dtsession*keys: fred,keith`
passwordTimeout	ClassClass: passwordTimeout Type: unsigned int Default: 10 Description: Specifies (in seconds) the amount of time before the password dialog is removed from the screen. When the display is locked, the pointer shows a lock cursor, and a dialog is displayed that asks for the user password. If no activity from the pointer or keyboard is detected for passwordTimeout seconds, the dialog is removed from the screen. The dialog is redisplayed as soon as a pointer or keyboard event is detected. A passwordTimeout of 0 leaves the password dialog in place for the entire time the display is locked. The default value is 10 seconds.

Miscellaneous Resources

Item	Description
queryServerSettings	ClassClass: QueryServerSettings Type: Boolean Default: False Description: Specifies whether the dtsession command queries the server at logout for all its settings, or whether it saves only those settings set by using the desktop Style Manager. Querying the server ensures that all settings are saved; however, there is a degradation in performance when a full query is done. The default value is False, which means that the server will not be queried.
saveFontPath	ClassClass: SaveFontPath Type: Boolean Default: False
wmStartupCommand	ClassClass: WmStartupCommand Type: executable path Default: NULL Description: Allows for an alternate window manager to be started at login. If this resource is NULL, dtsession starts /usr/dt/bin/dtwm. An alternate startup might look like: `Dtsession*wmStartupCommand: /usr/bin/X11/mwm` The command should not have any commands to a shell in it, and it should not be surrounded by quotes. If any other window manager other than /usr/dt/bin/dtwm is used, clients will be restored but might not be restored to the correct position. By default, this resource contains a NULL value.

Flags

Item	Description
-migrate	Instructs dtsession to migrate the resource information saved from a previous session. If this option is specified, client restart information from a previously saved session might be ignored. This option should only be required if the previous session was saved on AIX® 4.1.1 or AIX 4.1.2, and would normally be specified by modifying the /usr/dt/bin/Xsession script. The /usr/dt/bin/Xsession script contains information about how to modify that script to specify this option for dtsession.

Item

Description

-migrate

Instructs dtsession to migrate the resource information saved from a previous session. If this option is specified, client restart information from a previously saved session might be ignored. This option should only be required if the previous session was saved on AIX® 4.1.1 or AIX 4.1.2, and would normally be specified by modifying the /usr/dt/bin/Xsession script. The /usr/dt/bin/Xsession script contains information about how to modify that script to specify this option for dtsession.

Exit Status

The following exit values are returned:

Item	Description
0	Successful completion.
>0	An error occurred.

Examples

To start the session manager from the command line without restoring the previous session, enter:
```
dtsession -norestore
```

Location

/usr/dt/bin/dtsession

Files

Item	Description
/usr/dt/config/$LANG/sys.session	The desktop default set of applications for the user's Initial Session.
/etc/dt/config/$LANG/sys.session	System administrator-specified set of applications for the user's Initial Session.
/usr/dt/config/$LANG/sys.resources	The desktop default resources.
/etc/dt/config/$LANG/sys.resources	The system administrator-specified resources.
$HOME/.Xdefaults	The user-specified resources. Note: The dtsession command stores session information in $HOME/.dt/display or $HOME/.dt/sessions. The content of these directories should not be directly edited by the user.
/usr/dt/app-defaults/$LANG/Dtsession	Default dtsession resources.