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 those provided by init, getty, and login on character terminals:

prompting for login/password

authenticating the user

running a “session”

A session is defined by the lifetime of a particular UNIX System 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 reducing 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. Look through the various sections, picking and choosing the things you want to change. Pay particular attention to the section “The Xsession Program,” which will describe how to set up the style of session desired.

OPTIONS

First, note that all of these options except −config specify values that can also be specified in the configuration file as resources.

−config configuration_file
Specifies a resource file that provides 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 resource DisplayManager.daemonMode. 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 resource DisplayManager.debugLevel. A nonzero value causes xdm to print piles of debugging statements to the terminal; it also disables the DisplayManager.daemonMode resource, forcing xdm to run syncronously.

−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.

−nodaemon
Specifies “false” as the value for the resource DisplayManager.daemonMode.

-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, just as in 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 the article on resource files (doc/tutorials/resources.txt), by Jim Fulton, for a description of the format. 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 that 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 new-line characters) that are local to this host. If the resource value begins with a slash (/), it is assumed to be the name of a UNIX System 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:

locallocal display which receives multiple sessions
localTransient local display which has only one session run
foreignremote display which receives multiple sessions
transientremote 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 System path name, so that 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 normally directed at the system console. To redirect it simply set this resource to any file name. A method to send these messages to syslog should be developed for systems which 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 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 database is loaded just before the authentication procedure is started, so it can control the appearance of the login window. See the section “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 section “The Xstartup File” below.

DisplayManager.DISPLAY.session
This 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 Xsession Program” 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 section “The Xreset File.”

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 behavior 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 because 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
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 PATH environment variable for the session to this value. It should be a colon separated list of directories, see sh(1) for a full description. The default value can be specified in the X system configuration file with DefUserPath; frequently it is set to :/bin:/usr/bin:/usr/bin/X11:/usr/ucb.

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, 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 “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.hertz
xdm sets the HZ environment variable to the value of this resource. By default, it is 100.

DisplayManager.DISPLAY.timezone
xdm sets the TZ environment variable to the value of this resource. By default, it is EST5EDT.

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 it executes using the same environment variables as the session would have had (see the section “The Xsession Program”). By default, /usr/bin/X11/xterm is used.

CONTROLLING THE SERVER

xdm controls local servers using UNIX System 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 heirarchy 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 which does not have any bits drawn when displayed. In the default font, 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, it proceeds to the password field; if the cursor is in the password field, it checks 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 it 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 “The Xsession Program” and “Typical Usage.”

The Xstartup File

This file is typically a shell script. It is run as root, and you should be very careful about security. This is the place to put commands which make fake entries in /etc/utmp, to mount users’ home directories from file servers, to display the message of the day, or to 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
HOMEis set to the home directory of the user
USERis set to the user name
PATHis set to the value of DisplayManager.DISPLAY.systemPath
SHELLis set to the value of DisplayManager.DISPLAY.systemShell
LOGNAME is set to the user’s login name (from /etc/passwd)
HZis set to the value of DisplayManager.DISPLAY.hertz
TZis set to the value of DisplayManager.DISPLAY.timezone

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 nonzero, 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
HOMEis set to the home directory of the user
USERis set to the user name
PATHis set to the value of DisplayManager.DISPLAY.userPath
SHELLis set to the user’s default shell (from /etc/passwd)
LOGNAME is set to the user’s login name (from /etc/passwd)
HZis set to the value of DisplayManager.DISPLAY.hertz
TZis set to the value of DisplayManager.DISPLAY.timezone

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.”

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 “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/inittab or manually.

First, 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

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 section “RESOURCES” 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 explanations for the trouble.

The next configuration entry, /usr/lib/X11/xdm/Xresources, is loaded onto the display as a resource database using xrdb(1). Because 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 not look good on other monitors. As X does not currently have any standard color naming scheme, you might need to tune these entries to avoid undesirable 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 #override is not specified, the default translations are removed and replaced by the new value; this is not a very useful result as some of the default translations are quite useful, such as "<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 is no core X client that displays files), the user will probably be baffled by this behavior. This is not 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, 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 ugly window manager and
                # use xterm as the session control process.
                #
                if [ -f $resources ]; then
                        xrdb -load $resources
                fi
                uwm &
                exec xterm -geometry 80x24+10+10 -ls
        fi

Finally, the Xreset script in this demonstration is particularly 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 /etc/init option 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 similar to that of init(1).

BUGS

One thing that xdm is not very good at doing is coexisting with other window systems. To use multiple window systems on the same hardware, you will probably be more interested in xinit.

COPYRIGHT

AUTHOR

Keith Packard, MIT X Consortium.

\*U — Version 1.0

Museum

Related Articles