Xsession(5) X11 5.4R3.00 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 compatibility 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 usually 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 category are not X clients, but commands
usually found in a user's .profile or .login file (see sh(1) or
csh(1) man page for an explanation 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 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
Licensed material--property of copyright holder(s) 1
Xsession(5) X11 5.4R3.00 Xsession(5)
over, and will restart the Xserver (or in the case of an X-terminal
kill all the clients), and redisplay the login widget.
A 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 compatibility 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 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 prevents 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
Licensed material--property of copyright holder(s) 2
Xsession(5) X11 5.4R3.00 Xsession(5)
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
/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) 3