XDM(1X11) COMMAND REFERENCE XDM(1X11) 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] This is a user-contributed client. DESCRIPTION The X display manager 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* operating 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 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 will describe how to set up the style of session desired. Printed 3/22/89 1
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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 behavior. -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(1x11) 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 most toolkit applications. Printed 3/22/89 2
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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. 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* operating 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: local a local display which receives multiple sessions localTransient a 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. The type-dependent entry for local servers is a program name and its arguments. The program name should be an absolute UNIX* operating system 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 Printed 3/22/89 3
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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(1x11) as the resource data-base 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/xterm 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 further on in this document. DisplayManager.DISPLAY.openDelay DisplayManager.DISPLAY.openRepeat Printed 3/22/89 4
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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 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 The xdm program 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 The xdm program 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 Printed 3/22/89 5
XDM(1X11) COMMAND REFERENCE XDM(1X11) configuration file, but it is frequently "/etc:/bin:/usr/bin:/usr/bin/X11:/usr/ucb". DisplayManager.DISPLAY.systemShell The xdm program 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). By default, /usr/bin/X11/xterm is used. CONTROLLING THE SERVER The xdm program controls local servers using UNIX* operating 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 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 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 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 Printed 3/22/89 6
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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. The xrdb program strips trailing white space from resource values, so to add spaces at the end of the prompt, 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 control-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. Printed 3/22/89 7
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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-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 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-beginning 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. Printed 3/22/89 8
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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 USES. The Xstartup file This file is typically a shell script. It is run as "root". This is the place to put commands which make fake entries in /etc/utmp, 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: DISPLAY is 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. The xdm program 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. Printed 3/22/89 9
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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: DISPLAY is 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 EXAMPLES. 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 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. EXAMPLES First, the xdm configuration file should be set up. A good thing to do is to make a directory, for example: /usr/lib/X11/xdm. It should 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 Printed 3/22/89 10
XDM(1X11) COMMAND REFERENCE XDM(1X11) 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. 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(1x11). 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 Xstartup file used here simply prevents login while the file /etc/nologin exists. Here is a sample Xstartup script: #!/bin/sh # # Xstartup # Printed 3/22/89 11
XDM(1X11) COMMAND REFERENCE XDM(1X11) # 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 UNIX operating # systems, check with local authorities before proceeding... # if [ -f $startup ]; then if [ -x $startup ]; then exec $startup else exec /bin/sh $startup fi else # Printed 3/22/89 12
XDM(1X11) COMMAND REFERENCE XDM(1X11) # 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 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 for a description of using signals to enable and disable these terminals in a manner reminiscent of init(8). CAVEATS The program doesn't coexist well with other window systems. To use multiple window systems on the same hardware, you may want to use xinit. SEE ALSO X(1x11), xinit(1x11). AUTHOR Keith Packard, MIT X Consortium *UNIX is a registered trademark of AT&T. Printed 3/22/89 13
%%index%% na:288,75; sy:363,588; de:951,2216; op:3527,4859;8746,3131;12237,5449;18046,5440;23846,4680;28886,4939;34185,2316;36861,3155;40376,2583; ex:42959,866;44185,2238;46783,1564;48707,1510; ca:50217,244; se:50461,285; %%index%%000000000245