xdm Command

Purpose

Manages a collection of X Displays with support for XDMCP.

Syntax

xdm [  -config ConfigurationFile] [  -debug DebugLevel ] [  -nodaemon ] [  -error ErrorLogFile ] [  -resources ResourceFile ] [  -server ServerEntry ] [  -udpPort PortNumber ] [  -session SessionProgram ] [  -xrm ResourceSpecification ]

Description

The xdm (X Display Manager) command manages a collection of X displays, which may be on the local host or remote servers. The design of the xdm command was guided by the needs of X terminals as well as the X Consortium standard XDMCP, the X Display Manager Control Protocol. The xdm command provides services similar to those provided by the init, getty, and login commands on character terminals: prompting for login name and password, authenticating the user, and running a session.

A session is defined by the lifetime of a particular process; in the traditional character-based terminal world, it is the user's login shell. In the xdm context, it is an arbitrary session manager. This is because in a windowing environment, a user's login shell process does not necessarily have any terminal-like interface with which to connect. When a real session manager is not available, a window manager or terminal emulator is typically used as the session manager, meaning that ending this process ends the user's session.

When the session is ended, xdm resets the X server and (optionally) restarts the whole process.

When the xdm command receives an Indirect query by way of XDMCP, it can run a chooser process to perform an XDMCP BroadcastQuery (or an XDMCP Query to specified hosts) on behalf of the display and offer a menu of possible hosts that offer XDMCP display management. This feature is useful with X terminals that do not offer a host menu themselves.

Because the xdm command provides the first interface that users see, it is designed to be simple to use and easy to customize to the needs of a particular site.

Typical Usage

The xdm command is designed to operate in a wide variety of environments.

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.pidFile:       /usr/lib/X11/xdm/xdm-pid
DisplayManager._0.authorize:  true
DisplayManager*authorize:     false

This file contains references to other files. Some of the resources are specified with an * (asterisk) separating the components. These resources can be made unique for each display by replacing the * (asterisk) with the display name, but typically this is not useful. See the Resources section on the next page for a complete discussion.

The first file, /usr/lib/X11/xdm/Xservers, contains the list of displays to manage that are not using XDMCP. Most workstations have only one display, numbered 0 (zero), so the file looks something like this:

:0 Local local /usr/bin/X11/X -force

This keeps /usr/bin/X11/X running on this display and manages a continuous cycle of sessions.

The /usr/lib/X11/xdm/xdm-errors file contains error messages from xdm and anything output to standard error by Xsetup, Xstartup, Xsession or Xreset scripts. If you have trouble starting the xdm command, check the /usr/lib/X11/xdm/xdm-errors file to see if the xdm command 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 the xrdb command. As the authentication widget reads this database before starting up, it usually contains parameters for that widget.

Flags

All of these options (except -config) specify values that can also be specified in the configuration file as resources.

Resources

At many stages, the actions of xdm can be controlled through the use of its configuration file, which is in the X resource format. Some resources modify the behavior of xdm on all displays, while others modify its behavior on a single display. When 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 and dots to separate resource name parts, xdm substitutes underscores for both dots and colons when generating the resource name.

XDMCP Access Control

The database file specified by the DisplayManager.accessFile resource provides information that the xdm command uses to control access from displays requesting XDMCP service. This file contains three types of entries:

• Entries that control the response to Direct and Broadcast queries.
• Entries that control the response to Indirect queries.
• Macro definitions.

Direct query entries contain either a host name or a pattern, which is distinguished from a host name by the inclusion of one or more pattern-matching characters. An * (asterisk) matches any sequence of 0 (zero) or more characters, and a ? (question mark) matches any single character. These are compared against the host name of the display device. If the entry is a host name, all comparisons are done using network addresses, so that any name that converts to the correct network address may be used. For patterns, only actual host names are used in the comparison, so ensure that you do not attempt to match aliases. Preceding either a host name or a pattern with an ! (exclamation point) causes hosts that match that entry to be excluded.

An Indirect entry also contains a host name or pattern, but follows it with a list of host names or macros to which indirect queries should be sent.

A macro definition contains a macro name and a list of host names and other macros that the macro expands to. To distinguish macros from host names, macro names start with a % (percent) character. Macros may be nested.

Indirect entries may also specify to have the xdm command run the chooser command to offer a menu of hosts to which to connect. For more information, see Chooser.

When checking access for a particular display host, each entry is scanned in turn and the first matching entry determines the response. For example, a Direct query entry is ignored when scanning for an Indirect entry. A Broadcast query entry is ignored when scanning for a Direct entry.

Blank lines are ignored. The # character is treated as a comment delimiter causing the rest of that line to be ignored, and a \ (backslash) at the end of the line causes the new line to be ignored, allowing indirect host lists to span multiple lines.

The following is an example Xaccess file:

#
# Xaccess - XDMCP access control file
#

#
# Direct/Broadcast query entries
#

!xtra.lcs.mit.edu       # disallow direct/broadcast service for xtra
bambi.ogi.edu     # allow access from this particular display
*.lcs.mit.edu     # allow access from any display in LCS

#
# Indirect query entries
#

%HOSTS          expo.lcs.mit.edu xenon.lcs.mit.edu \\
               excess.lcs.mit.edu kanga.lcs.mit.edu

extract.lcs.mit.edu    xenon.lcs.mit.edu    #force extract to contact xenon
!xtra.lcs.mit.edu         dummy     #disallow indirect access
*.lcs.mit.edu     %HOSTS           #all others get to choose

Chooser

For X terminals that do not offer a host menu for use with Broadcast or Indirect queries, the chooser program can do this for them. In the Xaccess file, specify CHOOSER as the first entry in the Indirect host list. The chooser program sends a Query request to each of the remaining host names in the list and offers a menu of all the hosts that respond.

The list may consist of the word BROADCAST, in which case chooser sends a Broadcast query instead, again offering a menu of all hosts that respond.

The following is an example Xaccess file using chooser:

extract.lcs.mit.edu       CHOOSER   %HOSTS         #offer a menu of these hosts
xtra.lcs.mit.edu          CHOOSER   BROADCAST      #offer a menu of all hosts

The program to use for chooser is specified by the DisplayManager.DISPLAY.chooser resource. Resources for this program can be put into the file named by the DisplayManager.DISPLAY.resources resource.

The chooser has been implemented using a Motif SelectionBoxWidget. Refer to the XmSelectionBoxWidget Class documentation for a description of resources and widget or gadget names.

Server Specification

The resource DisplayManager.servers gives a server specification or, if the values starts with a / (slash), the name of a file containing server specifications, one per line.

Each specification indicates a display that should constantly be managed and that is not using XDMCP. Each consists of at least three parts:

• Display name
• Display class
• Display type
• For local servers, a command line to start the server.

A typical entry for local display number 0 would be:

:0 IBM-GT local /usr/bin/X11/X :0

The display types are:

The display name must be something that can be passed in the -display option to an X program. This string is used to generate the display-specific resource names, so be careful to match the names (for example, use ":0 local /usr/bin/X11/X :0" instead of "`localhost:0 local /usr/bin/X11/X :0" if your other resources are specified as "DisplayManager._0.session"). The display class portion is also used in the display-specific resources as the class of the resource. This is useful if you have a large collection of similar displays (like a corral of X terminals) and would like to set resources for groups of them. When using XDMCP, the display is required to specify the display class, so the manual for your particular X terminal should document the display class string for your device. If it does not, you can run the xdm command in debug mode and look at the resource strings that it generates for that device, which will include the class string.

Setup Program

The Xsetup file is run after the server is reset, but before the login window is offered. The file is typically a shell script. It is run as root, so be careful about security. This is the place to change the root background or bring up other windows that should be displayed on the screen along with the Login widget. Because xdm grabs the keyboard, other windows will not be able to receive keyboard input. They will be able to interact with the mouse, however; beware of potential security holes here. If DisplayManager.DISPLAY.grabServer is set, Xsetup will not be able to connect to the display at all. Resources for this program can be put into the file named by DisplayManager.DISPLAY.resources.

In addition to any specified by DisplayManager.exportList, the following environment variables are passed:

Authentication Client

The MIT authentication widget has been replaced by an authentication client composed of standard Motif widgets. The following is a list of the widget names (and their widget class):

outframe(xmFrameWidget)
  inframe(xmFrameWidget)
    main(XmFormWidget)
      tframe(xmFrameWidget)
        greeting(xmLabelGadget)
      logoline(xmFormWidget)
        dpyname(xmLabelWidget)
      userline(xmRowColumnWidget)
        userlabel(xmLabelWidget)
        username(xmTextWidget)
        passlabel(xmLabelWidget)
        password(xmTextWidget)
      failsafeline(xmFormWidget)
        failsafe(xmToggleButtonWidget)
      cancelline(xmFormWidget)
        cancel(xmPushButtonWidget)
      message(xmLabelWidget)

The authentication client reads a name/password pair from the keyboard. Put resources for this client into the file named by DisplayManager.DISPLAY.resources. All of these have reasonable default values, so it is unnecessary to specify any of them. See /usr/lib/X11/xdm/Xresources for more information on default values for authentication client resources as well as the appropriate widget class documentation. The following resources are also supported by the authentication client:

Ctrl<Key>b: backward-character()\n\
Ctrl<Key>a: beginning-of-line()\n\
Ctrl<Key>e: end-of-line()\n\
Ctrl<Key>f: forward-character()\n\
Ctrl<Key>d: kill-next-character()\n\
Ctrl<Key>k: kill-to-end-of-line()\n\
Ctrl<Key>u: kill-to-start-of-line()\n

Xlogin*XmText.translations: #override\n\

<Key>osfHelp:    set-session-argument(failsafe) finish-field()\n\
Ctrl<Key>Return: set-session-argument(failsafe) finish-field()\n\
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\
<Key>Return:     finish-field() \n
<Key>BackSpace:  delete-previous-character() \n\
<Key>Delete:     delete-previous-character() \n

Startup Program

The Xstartup file is typically a shell script. Because it is run as the root user, be careful about security when it runs. It usually contains commands that add entries to /etc/utmp, mount users' home directories from file servers, display the message of the day, or cancel the session if logins are not allowed.

In addition to the environment variables specified by DisplayManager.exportList, the following variables are passed:

No arguments are passed to the script. The xdm command waits until this script exits before starting the user session. If the exit value of this script is nonzero, the xdm command discontinues the session and starts another authentication cycle.

Session Program

The Xsession program establishes the style of the user's session. It is run with the permissions of the authorized user.

In addition to any specified by DisplayManager.exportList, the following environment variables are passed:

At most installations, the Xsession program should look in the user's home directory ($HOME) for a file .xsession, which contains the commands that the user would like to use as a session. The Xsession program should also implement a 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. Usually, this feature is used to allow the user to escape from the ordinary session when it fails. This allows users to repair their own .xsession if it fails, without requiring administrative intervention. The section Typical Usage demonstrates this feature.

Reset Program

The Xreset script is run after the user session has ended. Run as root, it should contain commands that undo the effects of commands in Xstartup by removing entries from /etc/utmp or unmounting directories from file servers. The environment variables that are passed to Xstartup are also passed to Xreset. This program is symmetrical with the Xstartup program.

Controlling the Server

The xdm command controls local servers using POSIX signals. The SIGHUP signal is expected to reset the server, closing all client connections and performing other cleanup duties. The SIGTERM signal is expected to cancel the server. If these signals do not perform the expected actions, the resources DisplayManager.DISPLAY.resetSignal and DisplayManager.DISPLAY.termSignal can specify alternate signals.

To control remote terminals that are not using XDMCP, the xdm command 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 cause all of the clients to become inactive, because only those that have created windows will be noticed. XDMCP provides a more sure mechanism; when the xdm command closes its initial connection, the session is over and the terminal is required to close all other connections.

Controlling XDM

The xdm command responds to two signals: SIGHUP and SIGTERM. When sent a SIGHUP, xdm rereads the configuration file, the access control file, and the servers file. For the servers file, it notices if entries have been added or removed. If a new entry has been added, the xdm command starts a session on the associated display. Entries that have been removed are disabled immediately, meaning that any session in progress is ended without notice and no new session is started.

When sent a SIGTERM, the xdm command stops all sessions in progress and exits. This can be used when shutting down the system.

The xdm command attempts to mark its various subprocesses for use by the ps command by editing the command-line argument list in place. Because the xdm command cannot allocate additional space for this task, it is useful to start the xdm command with a reasonably long command line (using the full path name should be enough). Each process that is servicing a display is marked -display.

Other Possibilities

You can use the xdm command to run a single session at a time, using the xinit command options or other suitable daemons by specifying the server on the command line:

xdm -server ":0 local /usr/bin/X11/X :0 -force"

It might also run a file server and a collection of X terminals. The configuration for this is identical to the previous sample, except the Xservers file would look like the following:

        extol:0 VISUAL-19 foreign
        exalt:0 NCD-19 foreign
        explode:0 NCR-TOWERVIEW3000 foreign

Examples

1. The sample xstartup script that follows 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 setup in this example is not recommended because the login would fail without explanation. Thus, this is not a complete example, but a demonstration of the available functionality.

   #!/bin/sh
   #
   # Xstartup
   #
   # This program is run as root after the user is verified
   #
   if [ \-f /etc/nologin ]; then
           exit 1
   fi
   exit 0

2. This Xsession script recognizes the special failsafe mode, specified in the translations in the preceding Xresources file, to provide an escape from the ordinary session:

   #!/bin/sh
   exec > $HOME/.xsession-errors 2>&1
   case $# in
   1)
           case $1 in failsafe)
                  exec aixterm -geometry 80x24-0-0
                  ;;
           esac
   esac
   startup=$HOME/.xsession
   resources=$HOME/.Xresources
   if [ -f /usr/bin/X11/startx ]; then
          exec /usr/bin/X11/startx -t -wait
   elif [ -f $startup]; then
          exec $startup
   else
          if [ -f $resources ]; then
                  xrdb -load $resources
          fi
          mwm &
          exec aixterm -geometry 80x24+10+10 -ls
   fi

3. To have xdm come up from system startup, as root type the following:

   /usr/lib/X11/xdm/xdmconf

4. To disable xdm on reboot, as root type the following:

   /usr/lib/X11/xdm/xdmconf -d

5. When using xdm to manage your display, an authentication procedure insures that only clients that are allowed can connect to your display. Clients that are built using X11 R4 and X11 R5 libraries understand this protocol. Clients that are built with X11 R3 or earlier libraries do not support this authentication protocol and are not allowed to connect to the Xserver unless xhost permission is granted. You can connect local clients by typing the following:

   xhost =localhost

   or

   xhost =machine

   where machine is the hostname of the local client.

Files