# Configuring Session Manager

Session Manager is responsible for starting the desktop and automatically saving and restoring running applications, colors, fonts, mouse behavior, audio volume, and keyboard click.

Using Session Manager, you can:

- Customize the initial session for all desktop users

- Customize the environment and resources for all desktop users

- Change the session startup message

- Change parameters for session startup tools and daemons

- Customize desktop color usage for all users

SAG.SesMg.div.2
SAG.SesMg.div.7
SAG.SesMg.div.8
SAG.SesMg.div.21
SAG.SesMg.div.32

## What Is a Session?

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

### The Initial Session

When a user logs into the desktop for the first time, Session Manager will generate the user's initial session using system default values. By default, the File Manager and Information Manager will start. The Information Manager displays introductory information about the CDE desktop.

### Current Session

The user's running session 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, Session Manager automatically saves the current session. When the user next logs in to the desktop, Session Manager restarts the previously saved current session, meaning that the desktop will be restored to the same state as when the user last logged out.

### Home Session

You can also have the desktop restored 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 and then, using the Style Manager Startup settings, have Session Manager start that session every time the user logs in.

### Display-Specific Sessions

To run a specific session for a specific display, a user can create a display- specific session. To do this, the user can copy the HomeDirectory`/.dt/sessions` directory to HomeDirectory`/.dt/`display, where display is the real, unqualified host name (for example, `pablo:0` is valid, `pablo.gato.com:0` or `unix:0` is not). When the user logs in on display `pablo:0`, Session Manager will start that display-specific session.

## Starting a Session

Session Manager is started through `/usr/dt/bin/
Xsession`. When the user logs in using the Login Manager, `Xsession` is started by default.

Optionally, the user can log in using the traditional character mode
(`getty`) login, and start Session Manager manually using tools that start an X server, such as `xinit`. For example: `xinit /usr/dt/bin/Xsession`.

## When a Session Starts

When Session Manager is started, it goes through the following steps to start the user's session:

1. Sources the HomeDirectory`
   /.dtprofile` script

2. Sources the `
   Xsession.d` scripts

3. Displays a
   welcome message

4. Sets up
   desktop search paths

5. Gathers available applications

6. Optionally sources HomeDirectory`
   /.profile` or HomeDirectory`
   /.login`

7. Starts the
   ToolTalk® messaging daemon

8. Loads
   session resources

9. Starts the
   color server

10. Starts the
    Workspace Manager

11. Starts the session
    applications

The following sections describe the steps listed above.

### Sourcing the .dtprofile Script

At session startup, the `
Xsession` script sources the user's HomeDirectory`
/.dtprofile` script. The HomeDirectory`/.dtprofile` script is a `/bin/sh` or `/bin/ksh` script that enables users to set up
environment variables for their sessions. For more information on setting up environment variables, see SAG.SesMg.div.21.

If the HomeDirectory`/.dtprofile` script does not exist, such as when a user is logging into the desktop for the first time, `Xsession` will copy the desktop default `sys.dtprofile` to
HomeDirectory`
/.dtprofile`.

The desktop default is `/usr/dt/config/sys.dtprofile`
. To customize the
`sys.dtprofile` script, copy `sys.dtprofile` from `/usr/dt/config` to `/etc/dt/config` and edit the new file.

### Sourcing Xsession.d Scripts

After sourcing the HomeDirectory`/.dtprofile` script, the `Xsession` script sources the `Xsession.d` scripts. These scripts are used to set up additional environment variables and start optional daemons for the user's session. The default `Xsession.d` scripts are:

`0010.dtpaths` | Documents customizable desktop search paths
`0020.dtims` | Starts optional input method server
`0030.dttmpdir` | Creates per-user, per-session temporary directory
`0040.xmbind` | Sets up `$XMBINDDIR` to desktop default

There may be additional vendor-specific scripts in `Xsession.d`.

`Xsession` first sources all files in the `/usr/dt/config/Xsession.d` directory, followed by those in the `/etc/dt/config/Xsession.d` directory.

The desktop default `Xsession.d` scripts are located in the `/usr/dt/config/Xsession.d` directory. To customize an `Xsession.d` script, copy the script from `/usr/dt/config/Xsession.d` to `/etc/dt/config/Xsession.d` and edit the new file. You must have execute permission to perform this task.

Also, to have `Xsession` automatically source a script of your own, copy it to `/etc/dt/config/Xsession.d`.

When you modify or create an `Xsession.d` script, make sure that any foreground commands you issue are of short duration, as the time taken by the command will directly affect session startup time. If a foreground command does not exit, the session startup will hang. Commands run in an `Xsession.d` script that you want to remain running for the duration of the session should be run in the background.

###
Displaying the Welcome Message

After sourcing HomeDirectory`/.dtprofile` and the `Xsession.d` scripts, `Xsession` displays a welcome message that covers the screen. You can customize the welcome message displayed, or turn off the message entirely. The `dthello` client is used to display the message.

To alter the message text, change the `dthello` options by modifying the `dtstart_hello[0]` variable.

To change `dtstart_hello[0],` create an `/etc/dt/config/Xsession.d` script that sets the new value. To display the message of the day for all users, create an executable `sh` or `ksh` script, for example `/etc/dt/config/Xsession.d/`myvars`,` and set `dtstart_hello[0]` as follows:

    dtstart_hello[0]=“/usr/dt/bin/dthello -file /etc/motd &“

Similarly, users can change the welcome message for their sessions by setting `dtstart_hello[0]` in HomeDirectory`/.dtprofile`.

To turn off the welcome message, set `dtstart_hello[0]=`“ “`.`

For more information about `dthello`, see the `dthello` man page.

### Setting Up the Desktop Search Paths

The desktop search paths are created at login by `
dtsearchpath`. There are two categories of environment variables used by `dtsearchpath`:

Input Variables | System-wide and personal environment variables whose values are set by the system administrator or end user.
Output Variables | Variables created and assigned values by `dtsearchpath`. The value of each variable is the search path for the desktop session.

To alter the command-line options of `dtsearchpath`, modify the `dtstart_searchpath` variable. To change the `
dtstart_searchpath` variable for all users, create an executable `sh` or `ksh` script (for example `/etc/dt/config/Xsession.d/`myvars), and set `dtstart_searchpath` as follows:

    dtstart_searchpath=“/usr/dt/bin/dtsearchpath“

Users can similarly change the `dtsearchpath` options for their own sessions only by setting `dtstart_searchpath` in HomeDirectory`/.dtprofile`.

For more information about `dtsearchpath`, see SAG.Datab.div.1. For more information about `dtsearchpath` options, see the `dtsearchpath` man page.

### Gathering Available Applications

The next step after setting up the desktop search paths is to gather available applications, using `dtappgather`. To alter the command-line options of
`dtappgather`, modify the `dtstart_appgather` variable. To change the `
dtstart_appgather` variable for all users, create an executable `sh` or `ksh` script (for example `/etc/dt/config/Xsession.d/`myvars), and set `dtstart_appgather` as follows:

    dtstart_appgather=“/usr/dt/bin/dtappgather &“

Users can similarly change the `dtappgather` options for their own sessions only by setting `dtstart_appgather` in HomeDirectory`/.dtprofile`.

For more information about `dtappgather` options, see the `dtappgather` `(4)` man page.

### Optionally Sourcing the .profile or .login Script

`Xsession` is able to source a user's traditional HomeDirectory`/.profile` or HomeDirectory`/.login` scripts. By default this capability is disabled. To tell `Xsession` to source the `.profile` or `.login` script, set `
DTSOURCEPROFILE` to `true`.

To change `DTSOURCEPROFILE` for all users, create an `/etc/dt/config/Xsession.d` script that sets the new value. To set `DTSOURCEPROFILE` to `true` for all users, create an executable `sh` or `ksh` script, for example `/etc/dt/config/Xsession.d/`myvars, and set `DTSOURCEPROFILE` as follows:

    DTSOURCEPROFILE=true

Users can similarly change `DTSOURCEPROFILE` for their own sessions by setting `DTSOURCEPROFILE` to `true` in HomeDirectory`/.dtprofile`.

### Starting the ToolTalk Messaging Daemon

The ToolTalk messaging daemon, `ttsession`, enables independent applications to communicate with each other without having direct knowledge of each other. Applications create and send ToolTalk messages to communicate with each other. `ttsession` communicates on the network to deliver messages.

To alter the command-line options of `
ttsession`, modify the `dtstart_ttsession` variable. To change the `
dtstart_ttsession` variable for all users, create an executable `sh` or `ksh` script (for example `/etc/dt/config/Xsession.d/`myvars), and set `dtstart_ttsession` as follows:

    dtstart_ttsession=“/usr/dt/bin/ttsession -s“

Users can similarly change the `ttsession` options for their own sessions by setting `dtstart_ttsession` in HomeDirectory`/.dtprofile`.

For more information about `ttsession` options, see the `ttsession` man page. For more information on `ttsession`, see Getting Started Using ToolTalk Messaging.

### Starting the Session Manager Client

At this point, `Xsession` starts `/usr/dt/bin/dtsession`, which continues the session startup process.

### Loading the Session Resources

Session Manager uses the X server `RESOURCE_MANAGER` property to make desktop resources available to all applications. Session Manager loads the `RESOURCE_MANAGER` by:

- Loading the system default resources

- Merging any system-wide resources specified by the system administrator.

- Merging any user-specified resources

The desktop default resources can be found in `/usr/dt/config/`language`
/sys.resources`. These resources will be made available to each user's session via the `RESOURCE_MANAGER` property. This file should not be edited, as it is overwritten upon subsequent desktop installations.

You can augment the system default resources by creating `/etc/dt/config/`language`
/sys.resources`. In this file, you can override default resources or specify additional resources for all desktop users. Since this file is merged into the desktop default resources during session startup, only new or updated resource specifications should be placed in this file. Resources specified in this file will be 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.

Users can augment the desktop default and system-wide resources using their HomeDirectory`/.Xdefaults` file. Resources specified in this file will be made available to that user's session through the `RESOURCE_MANAGER` property. Resources specified in this file take precedence over those specified in the desktop default or system administrator resource files.

The X Toolkit Intrinsics utility specifies that it will load resources for an application from either `
RESOURCE_MANAGER` or from HomeDirectory`/.Xdefaults`, but not both. Ordinarily, this would mean that the user's HomeDirectory`/.Xdefault`s file would be ignored. However, Session Manager accommodates HomeDirectory/`
.Xdefaults` by merging it into the `RESOURCE_MANAGER` at session startup as described above. If a user changes HomeDirectory/`.Xdefaults`, the changes will not be visible to new applications until the user invokes the Reload Resources action. The
Reload Resources action will instruct Session Manager to reload the `RESOURCE_MANAGER` with the default, system-wide, and user-specified resources. This makes changes to the system-wide and personal resource files available to applications.

For more information see:

- SAG.FACol.div.2

- The `dtresourcesfile(4)`man page

### Starting the Color Server

Session Manager serves as the
color server for the desktop and provides the following set of `dtsession` 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

You can set color server resources for all users by creating `/etc/dt/config/`language`/sys.resources` and specifying the color server resources in that file.

Users can similarly set color server resources for their own sessions by specifying color server resources in HomeDirectory`/.Xdefaults`.

For more information about setting color server resources, see SAG.FACol.div.18.

### Starting Workspace Manager

Session Manager is responsible for starting Workspace Manager. By default `/usr/dt/bin/
dtwm` is started. An alternate window manager can be specified with the `
wmStartupCommand` resource.

You can specify an alternate window manager for all users by creating `/etc/dt/config/`language`/sys.resources` and specifying the full path name and options for the window manager with the `Dtsession*wmStartupCommand` resource in that file.

Users can similarly specify an alternate window manager for their own sessions only by specifying the `Dtsession*wmStartupCommand` resource in HomeDirectory`/.Xdefaults`.

For more information about the Window Manager, see SAG.WMCnf.div.1.

### Starting the Session Applications

At session startup, Session Manager will restart 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 `/usr/dt/config/`language`/sys.session`. This file should not be edited as it will be unconditionally overwritten upon subsequent desktop installations.

For more information, see the `dtsessionfile(4)` and `dtsessiondb(4)` man pages.

A system administrator can replace the set of applications that are started as part of the user's initial session by copying `/usr/dt/config/`language`/sys.session` to `/etc/dt/config/`language`/sys.session` and modifying the latter file. Unlike the resource files, this file will be 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.

## Additional Session Startup Customizations

This section covers:

- Setting environment variables

- Setting resources

- Using display-dependent sessions

- Running scripts at login

- Recovering a back-up session

### To Set Environment Variables

1. To set system-wide environment variables, create a file in the `/etc/dt/config/Xsession.d`
   directory that sets and
   exports the variable.

   For example, if you create an executable `sh` or `ksh` script, `/etc/dt/config/Xsession.d/`myvars,

   containing:

       export MYVARIABLE=“value“

   then the variable `MYVARIABLE` will be set in each user's environment at the next login.

2. To set personal environment variables, set the variable in HomeDirectory`
   /.dtprofile`.

   For example:

       export MYVARIABLE=“value“

   sets the variable `MYVARIABLE` in each user's environment at the next login.

Session Manager does not automatically read the `
.profile` or `
.login` file. However, it can be configured to use these files; see SAG.SesMg.mkr.6.

### To Set Resources

1. To set system-wide resources, add the resources to the file `/etc/dt/config/`language`/sys.resources`. (You may have to create the file.)

   `.
   dtprofile` only supports `/bin/sh` or `/bin/ksh` syntax.

   For example, if in `/etc/dt/config/C/sys.resources` you specify:

       AnApplication*resource: value

   then the resource `AnApplication*resource` will be set in each user's `RESOURCE_MANAGER` property at the next login.

2. To set personal resources, add the resources to the file HomeDirectory`/.Xdefaults`.

### To Set Display-Specific Resources

You can set display-specific resources for all desktop users on the system. Also, users can set display-specific resources limited to their own session. This enables you to specify resources depending upon which display the user uses to log in to the desktop.

1. To set display-specific resources for all desktop users on the system, create the file `/etc/dt/config/`language`/sys.resources` that specifies the display-specific resources.

2. To set personal display-specific resources, specify the resource in HomeDirectory`/.Xdefaults`.

You delimit these resources by enclosing them in `
cpp` conditional statements. A `
DISPLAY_`displayname macro is defined depending upon the value of the `$DISPLAY` variable. This is done by converting all. (period) and: (colon) characters to _ (underscores), stripping off any screen specification, and finally prefixing `DISPLAY_` to the result.

For example, a `$DISPLAY` of `:0` would be `DISPLAY_0`, and a `$DISPLAY` of `blanco.gato.com:0.0` would be `DISPLAY_blanco_gato_com_0`. The resulting value can be used as part of a `cpp` test in a session resource file. For example, if in `/etc/dt/config/C/sys.resources` you specify:

    Myapp*resource: value
    #ifdef DISPLAY_blanco_gato_com_0
    Myapp*resource: specialvalue1
    #endif
    #ifdef DISPLAY_pablo_gato_com_0
    Myapp*resource: specialvalue2
    #endif

the resource `MyApp*resource` will be set in `RESOURCE_MANAGER` to `specialvalue1` when the user logs in on display `blanco.gato.com:0`; `specialvalue2` when the user logs in on `pablo.gato.com:0;` and `value` when the user logs in on another display.

### To Change Applications for the Initial Session

You can specify alternate applications to start as part of a user's initial session.

1. Copy `/usr/dt/config/`language`/sys.session` to `/etc/dt/config/`language`/sys.session.`

2. Modify the new `
   sys.session` file.

   Each entry in `sys.session` appears as:

       dtsmcmd -cmd command_and_options

   To start an additional application as part of a user's initial session, specify a new `sys.session` entry with a full path name. For example, to start `/usr/bin/X11/xclock` as part of a user's initial session, add an `xclock` entry to `/etc/dt/config/C/sys.resources`:

       #
       # Start up xclock...
       #
       dtsmcmd -cmd “/usr/bin/X11/xclock -digital“

### To Set Up a Display-Specific Session

A user can set up a display-specific session to tune a session to a particular display.

1. Copy the HomeDirectory`/.dt/
   sessions` directory to HomeDirectory`/.dt/`display where display is the real, unqualified host name (`pablo:0` is valid, `pablo.gato.com:0` or `unix:0` is not).

For example, to create a display-specific session for display `pablo.gato.com:0`:

    cp -r HomeDirectory/.dt/sessions HomeDirectory/.dt/pablo:0

When the user next logs in on display `pablo.gato.com:0`, the Session Manager will start that display-specific session.

### Executing Additional Commands at Session Startup and Logout

Users can specify that additional commands be started when they log in to their desktop sessions. This is useful for setting up X settings that are not saved by Session Manager. For example, the user can use `xsetroot` to customize the root (workspace) pointer. Another use would be to start applications that are unable to be saved and restored by Session Manager. If an application will not restart when the session is restored, the user can start the client using this method.

### To Execute Additional Commands at Session Startup

1. Create the file HomeDirectory`/.dt/sessions/sessionetc` containing the commands.

   Generally this file is a script and must have execute permission. Processes started in `sessionetc` should be run in the background.

Do not use `sessionetc` to start clients that are automatically restored by Session Manager. Doing so can cause multiple copies of the application to be started. You may not be able to see the copies immediately because the windows may be stacked on top of one another.

### To Execute Additional Commands at Logout

A companion file to `sessionetc` is `
sessionexit`. Use `sessionexit` to perform some operation at session exit that is not handled by Session Manager.

1. Create the file HomeDirectory`/.dt/sessions/sessionexit`.

   Like `sessionetc`, this file is usually a script with execute permission.

### To Recover a Session from Backup

When Session Manager saves a session, the session information is stored in the HomeDirectory`/.dt/sessions` directory or in the HomeDirectory`/.dt/`display directory if using a display-specific session. In these directories, Session Manager creates a subdirectory named `current` or `home` to store information for the respective current or home session. Before the session information is stored, Session Manager makes a backup of the prior session with that name and stores it in `
current.old` or `
home.old`.

1. Log in using the Failsafe Session or Command Line Login from the login screen.

2. Copy the backup session directory to the active name. For example, to recover the backup home session:

    cp -r HomeDirectory/.dt/sessions/home.old HomeDirectory/.dt/sessions/home

Display-specific sessions can be recovered in the same manner.

### To Investigate Session Startup Problems

1. Check the file HomeDirectory`/.dt/startlog`.

   The `startlog` file will contain the output (`stderr`) from applications started by the Session Manager (on the Session Manager's host).

## Session Manager Files and Directories

- `/usr/dt/bin/Xsession`

- `/usr/dt/config/Xsession.d/*`

- `/usr/dt/bin/dtsession`

- `/usr/dt/bin/dtsession_res`

- HomeDirectory`/.dt/sessions/current`

- HomeDirectory`/.dt/sessions/home`

- HomeDirectory`/.dt/`display`/current`

- HomeDirectory`/.dt/`display/`home`