Xsession(5) X Version 11 (Release 5) Xsession(5)
NAME
Xsession - X Window System session management through xdm
DESCRIPTION
The primary function of xdm(1X) is to authenticate a user's
name and password, and startup a session manager to control
the user's session. By default the program .Xsession in the
user's home directory ($HOME/.Xsession) is executed as the
session manager. The session manager indicates the session
is over simply by exiting. xdm will then reset the
Xserver(1X) and put up a new login widget to start the cycle
over again.
.Xsession should be executable, and if it's a shell script
the first line should start with #! followed by the name of
the shell the script is written in. For example "#!/bin/sh".
.Xsession files which are not executable will be run as a
borne shell (/bin/sh) script for backward compatability
reasons only.
Two sample .Xsession files, sample.Xsession and
xstart.Xsession, are distributed in the directory
/usr/lib/X11/xdm. One of them should be copied into a
user's home directory as a .Xsession file (eg.
cp /usr/lib/X11/xdm/sample.Xsession $HOME/.Xsession).
sample.Xsession
sample.Xsession provides a starting point for users to make
a customized .Xsession file in their home directory. After
this file is copied into a user's home directory it can be
customized for a specific user. Three types of commands are
usally added to an .Xsession file:
Setup clients such as xset(1X), xsetroot(1X), xmodmap(1X)
and xrdb(1X), are used to set the appearance and default
values of the Xserver. These commands should be run in the
foreground (ie. the command should not end with an '&'),
since the actions of these clients need to be completed
before additional clients are started. Note these clients
will always run till completion and terminate without user
input.
Normal clients such as xterm(1X), xman(1X), xmag(1X), etc.
should be run in the background (ie. the command ends with
an '&'), since they will not terminate without user input.
Commands in the third catagory are not X clients, but
commands usally found in a user's .profile or .login file
(see sh(1) or csh(1) man page for an explaination of these
files). Examples include changing tty settings (see
stty(1)), and setting environment variables. The only
reason to add these types of commands to your .Xsession file
Licensed material--property of copyright holder(s) Page 1
Xsession(5) X Version 11 (Release 5) Xsession(5)
instead of your .profile or .login file, is if you did not
what them executed when you logged in not through xdm. Such
as logging in through a standard ASCII terminal, remote
login through rlogin or telnet, or executing an xterm with
the -ls option.
When the .Xsession file terminates, xdm will consider the
session over, and will restart the Xserver (or in the case
of an X-terminal kill all the clients), and redisplay the
login widget. Typically the last command in a .Xsession
file is to startup a window manager in the foreground.
Therefore, terminating the window manager (ie. selecting the
quit option on the window manager's popup menu) will
terminate the session.
Another typical usage is to have the last command be an
xterm started in the foreground. That xterm now becomes the
session control process. By exiting it (ie. logging out)
the session will be terminated. This is done in the system
default .Xsession file (/usr/lib/X11/xdm/system.Xsession),
which runs the user's login shell in a xterm as the last
foreground command. This is done mainly for security
reasons. A good example is the login sync, which has no
password, and simply runs the command /bin/sync (its login
shell) and exits. If the xterm was not the session
controlling process, the login shell (/bin/sync) would
terminate, but sync would still be logged in, and a new
xterm could be started from the window manager's popup menu,
logged in as sync.
Note there should be one and only one command run in the
foreground from the .Xsession file which requires user
input. That process becomes the session controlling process.
When it terminates, the session will terminate.
xstart.Xsession
xstart.Xsession provides backward compatability for
xstart(1X) users. By copying this file into your home
directory as .Xsession, it will provide the same environment
as xstart(1X) would, when logging in through xdm. The one
obvious exception is starting the Xserver, since it is
already running. The xstart(1X) server resource is simply
ignored.
If changes to the default Xserver startup command
("/usr/bin/X11/X :0 bc -bs") are desired, the xdm
configuration file /var/X11/xdm/Xservers can be changed. It
contains one entry for each server being managed. By default
the file contains one line ":0 local /usr/bin/X11/X :0 bc
-bs". The first field is the display name, the second is the
display type (local or foreign), and the third field is the
command to start local servers. Simply add your favorite
Licensed material--property of copyright holder(s) Page 2
Xsession(5) X Version 11 (Release 5) Xsession(5)
Xserver command line options to the end of the entry.
Execution of .Xsession
The user's .Xsession file is actually executed by the shell
script /usr/lib/X11/xdm/Xsession. Prior to running the
.Xsession file it first checks if the failsafe option is
set, in which case instead of running the user's .Xsession,
a single xterm is executed as the user's session. The
failsafe mode is useful if you make an error in your
.Xsession file which provents you from logging in.
After setting up several environment variables it runs a
command such as:
/usr/bin/X11/xterm -name xsession -title "session log" \
-e /bin/csh /usr/lib/X11/xdm/login-csh $HOME/.Xsession
In this example the user's login shell is /bin/csh. This
command will run any login scripts (eg. .profile, .login)
that are normally run when a user logins in through an ASCII
terminal. This is done by shell scripts with the prefix
"login-" in the directory /usr/lib/X11/xdm. If your login
shell is /bin/csh the file /usr/lib/X11/xdm/login-csh will
be used to simulate csh being run as a login shell.
And finally the .Xsession file will be run from the "login-"
file, which will inherit the xterm's tty device on its stdio
file descriptors. Therefore the "session log" xterm will
display any error messages from the .Xsession file and the
clients it starts.
Debugging
If your .Xsession file is a borne shell script the following
two lines can be added to the beginning of the file to aid
in debugging it:
set -x
trap "sleep 30" 0
The first command will echo each of the commands before they
are executed. The second command will cause the shell to
pause for 30 seconds before exiting. This will allow you
time to see the error messages on the "session log" xterm
before it terminates, and login widget reappears.
SEE ALSO
X(1X), Xserver(1X), xdm(1X), sh(1), csh(1), xterm(1X),
xrdb(1X), xstart(1X)
FILES
$HOME/.Xsession
/usr/lib/X11/xdm/sample.Xsession
Licensed material--property of copyright holder(s) Page 3
Xsession(5) X Version 11 (Release 5) Xsession(5)
/usr/lib/X11/xdm/xstart.Xsession
/usr/lib/X11/xdm/system.Xsession
/usr/lib/X11/xdm/Xsession
/usr/lib/X11/xdm/login-*sh
/usr/lib/X11/xdm/xdm-config
/var/X11/xdm/xdm-config
/var/X11/xdm/Xservers
Licensed material--property of copyright holder(s) Page 4