XDM(1) BSD XDM(1)
NAME
xdm - X Display Manager
SYNOPSIS
xdm [-config configuration_file] [-daemon] [-debug debug_level] [-error
error_log_file] [-nodaemon] [-resources resource_file] [-server
server_entry] [-session session_program] [-xrm resource_specification]
DESCRIPTION
Xdm 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 that provided by
init, getty and login on character terminals: prompting for
login/password, authenticating the user 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, with the condition that the lifetime
of the terminal emulator is the lifetime of the shell process that 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. Xdm 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 will describe how to set up the style of session desired.
OPTIONS
First, note that all of these options, except -config, specify values
which can also be specified in the configuration file as resources.
-config configuration_file
Specifies a resource file which specifies the remaining
configuration parameters. If no file is specified and the file
/usr/lib/X11/xdm/xdm-config exists, xdm will use 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 behaviour.
-debug debug_level
Specifies the numeric value for the DisplayManager.debugLevel
resource. A non-zero value causes xdm to print piles of debugging
statements to the terminal; it also disables the
DisplayManager.daemonMode resource, forcing 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 progress
of the session.
-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 (1) to specify configuration parameters
for the authentication widget.
-server server_entry
Specifies the value for the DisplayManager.servers resource. See
the section below which describes this resource in depth.
-xrm resource_specification
This allows an arbitrary resource to be specified, as with most
toolkit applications.
RESOURCES
At many stages the actions of xdm can be controlled through the use of
the configuration file, which is in the familiar X resource format. (See
Chapter 4 of "Using the X Window System on Apollo Workstations" for
additional information on X resources). Some resources modify the
behavior of xdm on all displays, while others modify its behavior on one
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 which defines
the startup shell file on the ``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
This resource lists the collection of servers (separated by
newlines) which 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:
local a local display which receives multiple sessions
localTransienta local display which has only one session run
foreign a remote display which receives multiple sessions
transient a remote display which 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 (e.g. 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 pathname as
xdm does not search through the directories of the PATH environment
variable.
For foreign servers, the type-dependent entry is ignored, but must
contain at least one word. These servers are typically X terminals
which want sessions run from a file server. In the future, it is
expected that the X terminal will negotiate the session startup, but
for now it is fixed by this resource specification.
DisplayManager.errorLogFile
Error output is sent to /usr/X11/lib/xdm/xdm-errors. To redirect
it, simply set this resource to any file name. This file also
contains any output directed to stderr by Xstartup, Xsession and
Xreset, so it will contain descriptions of problems in those scripts
as well.
DisplayManager.DISPLAY.resources
This resource specifies the name of the file to be loaded by xrdb
(1) as the resource database onto the root window of screen 0 of the
display. This resource data base is loaded just before the
authentication procedure is started, so it can control the
appearance of the "login" window. See the section below on the
authentication widget which describes the various resources which
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
This specifies a program which 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
Xstartup section below.
DisplayManager.DISPLAY.session
This specifies the session to be executed (not running as root). By
default, /usr/bin/X11/mterm is run. The conventional name is
Xsession. See the Xsession session below.
DisplayManager.DISPLAY.reset
This specifies a program which is run (as root) after the session
terminates. Again, by default no program is run. The conventional
name is Xreset. See the Xreset section later in this document.
DisplayManager.DISPLAY.openDelay
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 (2) syscall). 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 behaviour may seem arbitrary, it has been empirically
developed and 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 as a user can be spoofed by a look-alike window on
the display. If the grab fails, xdm kills and restarts the server.
DisplayManager.DISPLAY.terminateServer
This Boolean resource specifies whether the X server should be
terminated when a session terminates (instead of resetting it).
This option can be used 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
Xdm sets the session PATH environment variable to this value. It
should be a list of directories, with each entry separated by a
colon (see sh(1) for a full description). The default value can be
specified in the X system configuration file with DefUserPath.
DisplayManager.DISPLAY.systemPath
Xdm sets the PATH environment variable for the startup and reset
scripts to the value of this resource. The default for this
resource is specified with the DefaultSystemPath entry in the system
configuration file. It is recommended that "." not be included in
PATH. This is a good practice to follow for root; it avoids many
common trojan horse system penetration schemes.
DisplayManager.DISPLAY.systemShell
Xdm sets the SHELL environment variable for the startup and reset
scripts to the value of this resource. By default, it is "/bin/sh".
DisplayManager.DISPLAY.failsafeClient
If the default session fails to execute, xdm will fall back to this
program. This program is executed with no arguments, but executes
using the same environment variables as the session would have had
(see the section "Xsession" below). By default, /usr/bin/X11/mterm
is used.
CONTROLLING THE SERVER
Xdm controls local servers 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 will 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, as only those which have created windows will be noticed.
This is expected to change when better X terminal support is designed.
CONTROLLING XDM
Xdm 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 removed. If a new entry has been
added, xdm starts a session on the associated display. Entries which
have been removed are disabled immediately, meaning that any session in
progress will be terminated without notice, and no new session will be
started.
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 is an application which reads a name/password
pair from the keyboard. As this is a toolkit client, nearly every
imaginable parameter can be controlled with a resource. Resources for
this widget should be put into 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.width, xlogin.Login.height, xlogin.Login.x, xlogin.Login.y
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
The color used to display the typed-in user name.
xlogin.Login.font
The font used to display the typed-in user name.
xlogin.Login.greeting
A string which identifies this window. The default is "Welcome to
the X Window System".
xlogin.Login.greetFont
The font used to display the greeting.
xlogin.Login.greetColor
The color used to display the greeting.
xlogin.Login.namePrompt
The string displayed to prompt for a user name. Xrdb strips
trailing white space from resource values, so to add spaces at the
end of the prompt (usually a nice thing), add a character which is
*not* a space or a tab, and doesn't have any bits drawn when
displayed. In the default font, a ctrl-A suffices. The default is
"Login: "
xlogin.Login.passwdPrompt
The string displayed to prompt for a password. The default is
"Password: ".
xlogin.Login.promptFont
The font used to display both prompts.
xlogin.Login.promptColor
The color used to display both prompts.
xlogin.Login.fail
A message which is displayed when the authentication fails. The
default is "Login Failed".
xlogin.Login.failFont
The font used to display the failure message.
xlogin.Login.failColor
The color used to display the failure message.
xlogin.Login.failTimeout
The time (in seconds) that the fail message is displayed. The
default is 30 seconds.
xlogin.Login.translations
This specifies the translations used for the login widget. Refer to
the X Toolkit documentation for a complete discussion on
translations. The default translation table is:
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-begining() \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 which are supported by the widget are:
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-begining
Moves the cursor to the beginning of the editable text.
move-to-end
Moves the cursor to the end of the editable text.
erase-to-end-of-line
Erases all text after the cursor.
erase-line
Erases the entire text.
finish-field
If the cursor is in the name field, proceeds to the password field;
if the cursor is in the password field, check the current
name/password pair. If the name/password pair are valid, xdm starts
the session. Otherwise the failure message is displayed 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. It can be used to stop
xdm when shutting the system down, or when using xdmshell.
restart-session
Resets the X server and starts a new session. This can be used when
the resources have been changed 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 which is passed to the session at
startup. See the sections on Xsession and Typical usage.
The Xstartup file
This file is typically a shell script. It is run as "root" and should be
very careful about security. This is the place to put commands which
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. Various environment variables are set for the use of
this script:
DISPLAYis set to the associated display name
HOME is set to the home directory of the user
USER is set to the user name
PATH is set to the value of DisplayManager.DISPLAY.systemPath
SHELL is set to 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 this
script is non-zero, xdm discontinues the session immediately and starts
another authentication cycle.
The Xsession program
This is the command which is run as the user's session. It is run with
the permissions of the authorized user, and has several environment
variables specified:
DISPLAYis set to the associated display name
HOME is set to the home directory of the user
USER is set to the user name
PATH is set to the value of DisplayManager.DISPLAY.userPath
SHELL is set to the user's default shell (from /etc/passwd)
At most installations, Xsession should look in $HOME for a file .xsession
which would contain commands that each user would like to use 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 Typical Usage below.
An argument may be passed to this program from the authentication widget
using the `set-session-argument' action. This can be used to select
different styles of session. One very good use of this feature is to
allow the user to escape from the ordinary session when it fails. This
would allow users to repair their own .xsession if it fails, without
requiring administrative intervention. The section on typical usage
demonstrates this feature.
The Xreset file
Symmetrical with Xstartup, this script is run 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 that were passed to Xstartup are also given to
Xreset.
Typical Usage
Actually, xdm is designed to operate in such a wide variety of
environments that "typical" is probably a misnomer. However, this
section will focus on making xdm a superior solution to traditional means
of starting X from /etc/ttys or manually.
First off, the xdm configuration file should be set up. A good thing to
do is to make a directory (/usr/lib/X11/xdm comes immediately to mind)
which will contain all of the relevant files. Here is a reasonable
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 ``*'' separating the
components. These resources can be made unique for each different
display, by replacing the ``*'' with the display-name, but normally this
is not very useful. See the Reources section for a complete discussion.
The first file /usr/lib/X11/xdm/Xservers contains the list of displays to
manage. Most workstations have only one display, numbered 0, so the file
will look like this:
:0 local /usr/bin/X11/X :0
This will keep /usr/bin/X11/X running on this display and manage a
continuous cycle of sessions.
The file /usr/lib/X11/xdm/xdm-errors will contain 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.
The next configuration entry, /usr/lib/X11/xdm/Xresources, is loaded onto
the display as a resource database using xrdb (1). As 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
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. As X does not
currently have any standard color naming scheme, you might need to tune
these entries to avoid disgusting results. Please note the translations
entry; it specifies a few new translations for the widget which allow
users to escape from the default session (and avoid troubles that may
occur in it). Note that if #override is not specified, the default
translations are removed and replaced by the new value, not a very useful
result as 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. As there is no provision for displaying any
messages here (there isn't any core X client which displays files), the
user will probably be baffled by this behavior. I don't offer this as a
complete example, but simply a demonstration of the available
functionality.
Here is a sample Xstartup script:
#!/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
#
#
# 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, mterm frequently fails; but
# no other client will be as useful generally.
#
exec mterm -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 ugly window manager and
# use mterm as the session control process.
#
if [ -f $resources ]; then
xrdb -load $resources
fi
uwm &
exec mterm -geometry 80x24+10+10 -ls
fi
Finally, the Xreset script in this demonstration is particularily boring.
It does nothing:
#!/bin/sh
#
# Xreset
#
# This program is run as root after the session terminates but
# before the display is closed
#
SOME OTHER POSSIBILITIES
You can also use xdm to run a single session at a time, using the 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:
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 the section "Controlling Xdm" above for a description of using
signals to enable and disable these terminals in a manner reminiscent of
init(8).
One thing that xdm isn't very good at doing is coexisting with other
window systems. To use multiple window systems on the same hardware,
you'll probably be more interested in xinit .
SEE ALSO
X(1), xinit(1) and the proposed protocol for X terminal management.
BUGS
COPYRIGHT
Copyright 1988, Massachusetts Institute of Technology.
See X(1) for a full statement of rights and permissions.
AUTHOR
Keith Packard, MIT X Consortium