xdm(X) X Version 11 (11 July 1990) xdm(X)
NAME
xdm - X display manager
SYNOPSIS
xdm [-options ...]
DESCRIPTION
The xdm program manages a collection of X displays, both
local and possibly remote. The emergence of X terminals
guided the design of several parts of this system. It is
designed to provide services similar to those provided by
init, getty, and login on character terminals: prompting
for logins and passwords, authenticating users, and running
a session.
A session is defined by the lifetime of a particular UNIX
process; in the traditional character-based terminal world,
it is the user's login shell process. In the xdm context,
it is an arbitrary session manager. This is because in a
windowing environment, a user's login shell process would
not necessarily have any terminal-like interface with which
to connect.
Until real session managers become widely available, the
typical xdm substitute would be either a window manager with
an exit option or a terminal emulator running a shell-under
the condition that the lifetime of the terminal emulator
equals the lifetime of the shell process it is running-thus
degenerating the X session to an emulation of the
character-based terminal session.
When the session is terminated, xdm resets the X server and
(optionally) restarts the whole process.
Because xdm provides the first interface that users will
see, it is designed to be simple to use and easy to
customize to the needs of a particular site. The xdm
program has many options, most of which have reasonable
defaults. Browse through the various sections, picking and
choosing the things you want to change. Pay particular
attention to the Xsession section, which describes how to
set up the session style you want.
OPTIONS
Note that all of these options, except -config, specify
values that can also be specified as resources in the
configuration file.
-config configuration_file
Specifies a resource file that contains the remaining
configuration parameters. If no file is specified and
the file /usr/lib/X11/xdm/xdm-config exists, xdm uses
Page 1 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
it.
-daemon
Specifies ``true'' as the value for the
DisplayManager.daemonMode resource. This makes xdm
close all file descriptors, disassociate the
controlling terminal and put itself in the background
when it first starts up (just like the host of other
daemons). It is the default behavior.
-debug debug_level
Specifies the numeric value for the
DisplayManager.debugLevel resource. A nonzero value
causes xdm to print piles of debugging statements to
the terminal; it also disables the
DisplayManager.daemonMode resource, which forces xdm to
run synchronously.
-error error_log_file
Specifies the value for the DisplayManager.errorLogFile
resource. This file contains errors from xdm as well
as anything written to stderr by the various scripts
and programs run during the session progress.
-nodaemon
Specifies "false" as the value for the
DisplayManager.daemonMode resource.
-resources resource_file
Specifies the value for the DisplayManager*resources
resource. This file is loaded using xrdb (X) to
specify configuration parameters for the authentication
widget.
-server server_entry
Specifies the value for the DisplayManager.servers
resource. See the section below for an in-depth
description of this resource.
-xrm resource_specification
Allows you to specify an arbitrary resource.
RESOURCES
At many stages you can control the actions of xdm through
the configuration file, which is in the familiar X resource
format. Some resources modify the behavior of xdm on all
displays, while others modify its behavior on a single
display. Where actions relate to a specific display, the
display name is inserted into the resource name between
DisplayManager and the final resource name segment. For
example, DisplayManager.expo.0.startup is the name of the
resource that defines the start-up shell file on the
Page 2 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
"expo:0" display. Because the resource manager uses colons
to separate the name of the resource from its value, xdm
substitutes dots for the colons when generating the resource
name.
DisplayManager.servers
Lists the collection of servers (separated by new
lines) that are local to this host. If the resource
value begins with a slash, it is assumed to be the name
of a UNIX file containing the list. Each entry
consists of three parts: a display name, a display
type, and a type-dependent entry. A typical entry for
local display number 0 would be:
:0 local /usr/bin/X11/X :0
The display types are as follows:
local
A local display that receives multiple sessions.
localTransient
A local display that has only one session run.
foreign
A remote display that receives multiple sessions.
transient
A remote display that has only one session run. The
display name must be something that can be passed in the
-display option to any X program. This string is used
in the display-specific resources to specify the
particular display, so be careful to match the names.
Use:
:0 local /usr/bin/X11/X :0
instead of:
unix:0 local /usr/bin/X11/X :0
if your other resources are specified as:
DisplayManager..0.session)
The type-dependent entry for local servers is a program
name and its arguments. The program name should be an
absolute UNIX path name since xdm does not search
through the directories listed in the PATH environment
variable.
Page 3 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
For foreign servers, the type-dependent entry is ignored
but must contain at least one word. These servers are
typically X terminals that want sessions run from a file
server. In the future, it is expected that the X
terminal will negotiate the session start-up, but for
now it is fixed by this resource specification.
DisplayManager.errorLogFile
Error output is normally directed at the system console.
To redirect it, set this resource to any file name. A
method to send these messages to syslog should be
developed for systems that support it; however, the wide
variety of "standard" interfaces precludes any system-
independent implementation. This file also contains any
output directed to stderr by Xstartup, Xsession, and
Xreset, so it contains descriptions of problems in those
scripts as well.
DisplayManager.DISPLAY.resources
Specifies the name of the file xrdb loads as the
resource database onto the root window of display screen
0. This resource database is loaded just before the
authentication procedure starts, so it can control how
the login window appears. See the section below on the
authentication widget, which describes the various
resources that are appropriate to place in this file.
There is no default value for this resource, but the
conventional name is Xresources.
DisplayManager.DISPLAY.xrdb
Specifies the program used to load the resources. By
default, xdm uses /usr/bin/X11/xrdb.
DisplayManager.DISPLAY.startup
Specifies a program that is run (as root) after the
authentication process succeeds. By default, no program
is run. The conventional name for a file used here is
Xstartup. See the section below on Xstartup.
DisplayManager.DISPLAY.session
Specifies the session to be executed (not running as
root). By default, /usr/bin/X11/xterm is run. The
conventional name is Xsession. See the section on
Xsession below.
DisplayManager.DISPLAY.reset
Specifies a program that is run (as root) after the
session terminates. By default, no program runs. The
conventional name is Xreset. Refer to the section on
Xreset later in this document.
DisplayManager.DISPLAY.openDelay
Page 4 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
DisplayManager.DISPLAY.openRepeat
DisplayManager.DISPLAY.openTimeout
These numeric resources control the behavior of xdm when
attempting to open intransigent servers. openDelay is
the length of the pause (in seconds) between successive
attempts. openRepeat is the number of attempts to make,
and openTimeout is the amount of time to wait while
actually attempting the open (i.e., the maximum time
spent in the connect system call). After openRepeat
attempts have been made, or if openTimeout seconds
elapse in any particular attempt, xdm terminates and
restarts the server, attempting to connect again.
Although this behavior may seem arbitrary, it works
quite well on most systems. The default values are 5
for openDelay, 5 for openRepeat, and 30 for openTimeout.
DisplayManager.DISPLAY.grabTimeout
To eliminate obvious security shortcomings in the X
protocol, xdm grabs the server and keyboard while
reading the name/password. This resource specifies the
maximum time xdm will wait for the grab to succeed. The
grab may fail if some other client has the server
grabbed, or possibly if the network latencies are very
high. This resource has a default value of 3 seconds;
you should be cautious when raising it since a user can
be fooled by a look-alike window on the display. If the
grab fails, xdm kills and restarts the server.
DisplayManager.DISPLAY.terminateServer
Specifies whether the X server should be terminated when
a session terminates (instead of resetting it). You can
use this option when the server tends to grow without
bound over time in order to limit the amount of time the
server is run. The default value is False.
DisplayManager.DISPLAY.userPath
Sets the PATH environment variable for the session to
this value. The format is a colon-separated list of
directories. You can specify the default value in the X
system configuration file with DefUserPath; frequently
it is set to :/bin:/usr/bin:/usr/bin/X11:/usr/ucb.
DisplayManager.DISPLAY.systemPath
Sets the PATH environment variable for start-up and
resets scripts to the value of this resource. The
default for this resource is specified with the
DefaultSystemPath entry in the system configuration
file, but it is frequently
/etc:/bin:/usr/bin:/usr/bin/X11:/usr/ucb. Note the
conspicuous absence of "." from this entry. This is a
good practice to follow for root; it avoids many common
Page 5 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
unsuccessful penetration schemes.
DisplayManager.DISPLAY.systemShell
Sets the SHELL environment variable for start-up and
resets scripts to the value of this resource. By
default, it is /bin/sh.
DisplayManager.DISPLAY.failsafeClient
If the default session fails to execute, xdm falls back
to this program. This program executes with no
arguments but uses the same environment variables as the
session would have had (see the section on Xsession
below). By default, /usr/bin/X11/xterm is used.
CONTROLLING THE SERVER
The xdm program controls local servers by using UNIX
signals. SIGHUP is expected to reset the server, closing
all client connections and performing other clean-up duties.
SIGTERM is expected to terminate the server. If these
signals do not perform the expected actions, xdm does not
perform properly.
To control remote servers, xdm searches the window hierarchy
on the display and uses the protocol request KillClient in
an attempt to clean up the terminal for the next session.
This may not actually kill all of the clients since only
those that have created windows are noticed.
CONTROLLING XDM
The xdm program responds to two signals: SIGHUP and SIGTERM.
When sent a SIGHUP, xdm rereads the file specified by the
DisplayManager.servers resource and notices if entries have
been added or deleted. If a new entry has been added, xdm
starts a session on the associated display. Entries that
have been removed are disabled immediately, meaning that any
session in progress is terminated without notice and no new
session starts.
When sent a SIGTERM, xdm terminates all sessions in progress
and exits. This can be used when shutting down the system.
AUTHENTICATION WIDGET
The authentication widget application reads a name and
password pair from the keyboard. Since this is a toolkit
client, you can control nearly every imaginable parameter
with a resource. Resources for this widget belong in the
file named by DisplayManager.DISPLAY.resources. All of
these have reasonable default values, so it is not necessary
to specify any of them.
xlogin.Login.y
xlogin.Login.width, xlogin.Login.height, xlogin.Login.x,
Page 6 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
The geometry of the login widget is normally computed
automatically. If you wish to position it elsewhere,
specify each of these resources.
xlogin.Login.foreground
Specifies the color for displaying the typed-in user
name.
xlogin.Login.font
Specifies the font for displaying the typed-in user
name.
xlogin.Login.greeting
Specifies a string that identifies this window. The
default is "Welcome to the X Window System."
xlogin.Login.greetFont
Specifies the font for displaying the greeting.
xlogin.Login.greetColor
Specifies the color for displaying the greeting.
xlogin.Login.namePrompt
Specifies the string to prompt for a user name. The
xrdb program strips trailing white space from resource
values; to add spaces at the end of the prompt (usually
a nice thing), add a character that is not a space or a
tab and doesn't have any bits drawn when displayed. In
the default font, a ^A suffices. The default prompt is
"Login:".
xlogin.Login.passwdPrompt
Specifies the string to prompt for a password. The
default is "Password: ".
xlogin.Login.promptFont
Specifies the font for displaying both prompts.
xlogin.Login.promptColor
Specifies the color for displaying both prompts.
xlogin.Login.fail
Specifies the message displayed when the authentication
fails. The default is "Login Failed."
xlogin.Login.failFont
Specifies the font used for displaying the failure
message.
xlogin.Login.failColor
Specifies the color for displaying the failure message.
Page 7 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
xlogin.Login.failTimeout
Specifies how long (in seconds) the failure message
displays. The default is 30 seconds.
xlogin.Login.translations
Specifies the translations used for the login widget.
The default translation table is as follows:
Ctrl<Key>H: delete-previous-character() \n\
Ctrl<Key>D: delete-character() \n\
Ctrl<Key>B: move-backward-character() \n\
Ctrl<Key>F: move-forward-character() \n\
Ctrl<Key>A: move-to-beginning() \n\
Ctrl<Key>E: move-to-end() \n\
Ctrl<Key>K: erase-to-end-of-line() \n\
Ctrl<Key>U: erase-line() \n\
Ctrl<Key>X: erase-line() \n\
Ctrl<Key>C: restart-session() \n\
Ctrl<Key>\\: abort-session() \n\
<Key>BackSpace: delete-previous-character() \n\
<Key>Delete: delete-previous-character() \n\
<Key>Return: finish-field() \n\
<Key>: insert-char() \
The actions supported by the widget are as follows:
delete-previous-character
Erases the character before the cursor.
delete-character
Erases the character after the cursor.
move-backward-character
Moves the cursor backward.
move-forward-character
Moves the cursor forward.
move-to-beginning
Moves the cursor to the beginning of the text you can
edit.
move-to-end
Moves the cursor to the end of the text you can edit.
erase-to-end-of-line
Erases all text after the cursor.
erase-line
Erases the entire text.
Page 8 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
finish-field
If the cursor is in the name field, proceeds to the
password field; if the cursor is in the password field,
checks the current name and password pair. If the name
and password pair are valid, xdm starts the session.
Otherwise, the failure message displays and the user is
prompted to try again.
abort-session
Terminates and restarts the server.
abort-display
Terminates the server, disabling it. This is a rash
action and is not accessible in the default
configuration. You can use it to stop xdm when
shutting the system down or when using xdmshell.
restart-session
Resets the X server and starts a new session. You can
use this when you have changed the resources and you
want to test them or when the screen has been
overwritten with system messages.
insert-char
Inserts the character typed.
set-session-argument
Specifies a single-word argument that is passed to the
session at start-up time. See the sections on Xsession
and TYPICAL USAGE.
THE Xstartup FILE
This file is typically a shell script. You should run it as
root and be very careful about security. Use this file to
store commands that make fake entries in /etc/utmp, mount
users' home directories from file servers, display the
message of the day, or abort the session if logins are not
allowed. To use the Xstartup script, set these environment
variables as follows:
DISPLAY
The associated display name.
HOME
The user's home directory.
USER
The user name.
PATH
The value of DisplayManager.DISPLAY.systemPath.
Page 9 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
SHELL
The value of DisplayManager.DISPLAY.systemShell.
No arguments of any kind are passed to the script. xdm
waits until this script exits before starting the user
session. If the exit value of the script is nonzero, xdm
discontinues the session immediately and starts another
authentication cycle.
THE Xsession PROGRAM
The Xsession command runs as the user's session. It runs
with the permissions of the authorized user and has the
following environment variables specified:
DISPLAY
The associated display name.
HOME
The user's home directory.
USER
The user name.
PATH
The value of DisplayManager.DISPLAY.userPath.
SHELL
The user's default shell (from /etc/passwd).
At most installations, Xsession looks in $HOME for the
.xsession file, which contains commands each user uses as a
session. This would replace the system default session.
Xsession should also implement the system default session if
no user-specified session exists. See the section titled
TYPICAL USAGE below.
You can pass an argument to the Xsession program from the
authentication widget using the set-session-argument action.
You can use this to select different session styles. One
very good use of this feature is to allow users to escape
from the ordinary session when it fails. This way users can
repair their own .xsession file. The section on typical
usage demonstrates this feature.
THE Xreset FILE
Symmetrical with Xstartup, this script runs after the user
session has terminated. Run as root, it should probably
contain commands that undo the effects of commands in
Xstartup-removing fake entries from /etc/utmp or unmounting
directories from file servers. The collection of
environment variables passed to Xstartup is also given to
Xreset.
Page 10 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
TYPICAL USAGE
Actually, xdm is designed to operate in such a wide variety
of environments that "typical" is probably a misnomer.
However, this section focuses on making xdm a superior
solution to traditional means of starting X from /etc/ttys
or manually.
First you must set up the xdm configuration file. Make a
directory (/usr/lib/X11/xdm comes immediately to mind) to
contain all of the relevant files. Here is a sample
configuration file, which could be named xdm-config:
DisplayManager.servers: /usr/lib/X11/xdm/Xservers
DisplayManager.errorLogFile: /usr/lib/X11/xdm/xdm-errors
DisplayManager*resources: /usr/lib/X11/xdm/Xresources
DisplayManager*startup: /usr/lib/X11/xdm/Xstartup
DisplayManager*session: /usr/lib/X11/xdm/Xsession
DisplayManager*reset: /usr/lib/X11/xdm/Xreset
As you can see, this file simply contains references to other
files. Note that some of the resources are specified with an
asterisk (*) separating the components. You can make these
resources unique for each different display by replacing the
asterisk with the display name, but normally this is not very
useful. See the section on resources for more information.
The first file, /usr/lib/X11/xdm/Xservers, contains the list
of displays to manage. Most workstations have only one
display, numbered 0, so this file looks like this:
:0 local /usr/bin/X11/X :0
This keeps /usr/bin/X11/X running on this display and
manages a continuous cycle of sessions.
The file /usr/lib/X11/xdm/xdm-errors contains error messages
from xdm and anything output to stderr by Xstartup,
Xsession, or Xreset. When you have trouble getting xdm
working, check this file to see if xdm has any clues to the
trouble.
/usr/lib/X11/xdm/Xresources, which is the next configuration
entry, is loaded onto the display as a resource database
using xrdb (X). Since the authentication widget reads this
database before starting up, it usually contains parameters
for that widget:
xlogin*login.translations: #override\
<Key>F1: set-session-argument(failsafe) finish-field()\n\
<Key>Return: set-session-argument() finish-field()
xlogin*borderWidth: 3
#ifdef COLOR
Page 11 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
xlogin*greetColor: #f63
xlogin*failColor: red
xlogin*Foreground: black
xlogin*Background: #fdc
#else
xlogin*Foreground: black
xlogin*Background: white
#endif
The various colors specified here look reasonable on several
of the displays we have but may look awful on other
monitors. X does not currently have any standard color-
naming scheme, you might need to tune these entries to avoid
unattractive results. Please note the translations entry;
it specifies a few new translations for the widget that
allow users to escape from the default session (and avoid
troubles that may occur in it). Note that if you don't
specify #override, the default translations are removed and
replaced by the new value. This is not a very useful result
since some of the default translations are quite useful
(like <Key>: insert-char () which responds to normal
typing).
The Xstartup file used here simply prevents login while the
file /etc/nologin exists. Because there is no provision for
displaying any messages here (there isn't any core X client
that displays files), the user may be confused by this
behavior. The following example Xstartup script
demonstrates the functionality available:
#!/bin/sh
#
# Xstartup
#
# This program is run as root after the user is verified
#
if [ -f /etc/nologin ]; then
exit 1
fi
exit 0
The most interesting script is Xsession. This version
recognizes the special "failsafe" mode, specified in the
translations in the Xresources file above, to provide an
escape from the ordinary session:
#!/bin/sh
#
# Xsession
#
Page 12 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
#
# check to see if the failsafe option is desired
#
case $# in
1)
case $1 in
failsafe)
#
# this is about as failsafe as I can imagine,
# unfortunately, xterm frequently fails; but
# no other client will be as useful generally.
#
exec xterm -geometry 80x24+50+50
;;
esac
esac
startup=$HOME/.xsession
resources=$HOME/.Xresources
#
# check for a user-specific session and execute it
#
# Note: the -x flag to test is not supported
# in all versions of UNIX, check with local
# authorities before proceeding...
#
if [ -f $startup ]; then
if [ -x $startup ]; then
exec $startup
else
exec /bin/sh $startup
fi
else
#
# a simple default session. Check to see
# if the user has created a default resource
# file and load it, start the mwm window
# manager and use xterm as the session
# control process.
#
if [ -f $resources ]; then
xrdb -load $resources
fi
mwm &
exec xterm -geometry 80x24+10+10 -ls
fi
Finally, the Xreset script in this demonstration does
nothing:
Page 13 (printed 7/3/90)
xdm(X) X Version 11 (11 July 1990) xdm(X)
#!/bin/sh
#
# Xreset
#
# This program is run as root after
# the session terminates but
# before the display is closed
#
OTHER USES
You can also use xdm to run a single session at a time,
using the BSD 4.3 init options or other suitable daemon by
specifying the server on the command line:
xdm -server ":0 localTransient /usr/bin/X :0"
Or, you might have a file server and a collection of X
terminals. The configuration for this could look identical
to the sample above, except the Xservers file might look
like this:
extol:0 foreign X terminal on Keith's desk
exalt:0 foreign X terminal on Jim's desk
explode:0 foreign X terminal on Bob's desk
This would direct xdm to manage sessions on all three of
these terminals. See CONTROLLING XDM above for a
description of using signals to enable and disable these
terminals in a manner reminiscent of init.
Note that xdm does not coexist with other window systems
very well. To use multiple window systems on the same
hardware, you'll probably be more interested in xinit .
SEE ALSO
X(X)
xinit(X)
COPYRIGHT
Copyright 1988, Massachusetts Institute of Technology.
See X(X) for a full statement of rights and permissions.
AUTHOR
Keith Packard, MIT X Consortium.
Page 14 (printed 7/3/90)