1XDM(8) System Manager's Manual XDM(8)
2
6 xdm - X Display Manager with support for XDMCP, host chooser
7
9 xdm [ -config configuration_file ] [ -nodaemon ] [ -debug debug_level ]
10 [ -error error_log_file ] [ -resources resource_file ] [ -server
11 server_entry ] [ -session session_program ]
12
14 Xdm manages a collection of X displays, which may be on the local host
15 or remote servers. The design of xdm was guided by the needs of X ter‐
16 minals as well as The Open Group standard XDMCP, the X Display Manager
17 Control Protocol. Xdm provides services similar to those provided by
18 init, getty and login on character terminals: prompting for login name
19 and password, authenticating the user, and running a ``session.''
20 A ``session'' is defined by the lifetime of a particular process; in
22 the traditional character-based terminal world, it is the user's login
23 shell. In the xdm context, it is an arbitrary session manager. This
24 is because in a windowing environment, a user's login shell process
25 does not necessarily have any terminal-like interface with which to
26 connect. When a real session manager is not available, a window man‐
27 ager or terminal emulator is typically used as the ``session manager,''
28 meaning that termination of this process terminates the user's session.
29 When the session is terminated, xdm resets the X server and (option‐
31 ally) restarts the whole process.
32 When xdm receives an Indirect query via XDMCP, it can run a chooser
34 process to perform an XDMCP BroadcastQuery (or an XDMCP Query to speci‐
35 fied hosts) on behalf of the display and offer a menu of possible hosts
36 that offer XDMCP display management. This feature is useful with X
37 terminals that do not offer a host menu themselves.
38 Xdm can be configured to ignore BroadcastQuery messages from selected
40 hosts. This is useful when you don't want the host to appear in menus
41 produced by chooser or X terminals themselves.
42 Because xdm provides the first interface that users will see, it is de‐
44 signed to be simple to use and easy to customize to the needs of a par‐
45 ticular site. Xdm has many options, most of which have reasonable de‐
46 faults. Browse through the various sections of this manual, picking
47 and choosing the things you want to change. Pay particular attention
48 to the Session Program section, which will describe how to set up the
49 style of session desired.
50
52 xdm is highly configurable, and most of its behavior can be controlled
53 by resource files and shell scripts. The names of these files them‐
54 selves are resources read from the file xdm-config or the file named by
55 the -config option.
56 xdm offers display management two different ways. It can manage X
58 servers running on the local machine and specified in Xservers, and it
59 can manage remote X servers (typically X terminals) using XDMCP (the
60 XDM Control Protocol) as specified in the Xaccess file.
61 The resources of the X clients run by xdm outside the user's session,
63 including xdm's own login window, can be affected by setting resources
64 in the Xresources file.
65 For X terminals that do not offer a menu of hosts to get display man‐
67 agement from, xdm can collect willing hosts and run the chooser program
68 to offer the user a menu. For X displays attached to a host, this step
69 is typically not used, as the local host does the display management.
70 After resetting the X server, xdm runs the Xsetup script to assist in
72 setting up the screen the user sees along with the xlogin widget.
73 The xlogin widget, which xdm presents, offers the familiar login and
75 password prompts.
76 After the user logs in, xdm runs the Xstartup script as root.
78 Then xdm runs the Xsession script as the user. This system session
80 file may do some additional startup and typically runs the .xsession
81 script in the user's home directory. When the Xsession script exits,
82 the session is over.
83 At the end of the session, the Xreset script is run to clean up, the X
85 server is reset, and the cycle starts over.
86 The file /var/log/xdm.log will contain error messages from xdm and
88 anything output to stderr by Xsetup, Xstartup, Xsession or Xreset.
89 When you have trouble getting xdm working, check this file to see if
90 xdm has any clues to the trouble.
91
93 All of these options, except -config itself, specify values that can
94 also be specified in the configuration file as resources.
95 -config configuration_file
97 Names the configuration file, which specifies resources to con‐
98 trol the behavior of xdm. /etc/X11/xdm/xdm-config is the de‐
99 fault. See the section Configuration File.
100 -nodaemon
102 Specifies ``false'' as the value for the DisplayManager.daemon‐
103 Mode resource. This suppresses the normal daemon behavior,
104 which is for xdm to close all file descriptors, disassociate it‐
105 self from the controlling terminal, and put itself in the back‐
106 ground when it first starts up.
107 -debug debug_level
109 Specifies the numeric value for the DisplayManager.debugLevel
110 resource. A non-zero value causes xdm to print lots of debug‐
111 ging statements to the terminal; it also disables the Display‐
112 Manager.daemonMode resource, forcing xdm to run synchronously.
113 To interpret these debugging messages, a copy of the source code
114 for xdm is almost a necessity. No attempt has been made to ra‐
115 tionalize or standardize the output.
116 -error error_log_file
118 Specifies the value for the DisplayManager.errorLogFile re‐
119 source. This file contains errors from xdm as well as anything
120 written to stderr by the various scripts and programs run during
121 the progress of the session.
122 -resources resource_file
124 Specifies the value for the DisplayManager*resources resource.
125 This file is loaded using xrdb(1) to specify configuration pa‐
126 rameters for the authentication widget.
127 -server server_entry
129 Specifies the value for the DisplayManager.servers resource.
130 See the section Local Server Specification for a description of
131 this resource.
132 -udpPort port_number
134 Specifies the value for the DisplayManager.requestPort resource.
135 This sets the port-number which xdm will monitor for XDMCP re‐
136 quests. If set to 0, xdm will not listen for XDMCP or Chooser
137 requests. As XDMCP uses the registered well-known UDP port 177,
138 this resource should not be changed to a value other than 0, ex‐
139 cept for debugging.
140 -session session_program
142 Specifies the value for the DisplayManager*session resource.
143 This indicates the program to run as the session after the user
144 has logged in.
145 -xrm resource_specification
147 Allows an arbitrary resource to be specified, as in most X Tool‐
148 kit applications.
149
151 At many stages the actions of xdm can be controlled through the use of
152 its configuration file, which is in the X resource format. Some re‐
153 sources modify the behavior of xdm on all displays, while others modify
154 its behavior on a single display. Where actions relate to a specific
155 display, the display name is inserted into the resource name between
156 ``DisplayManager'' and the final resource name segment.
157 For local displays, the resource name and class are as read from the
159 Xservers file.
160 For remote displays, the resource name is what the network address of
162 the display resolves to. See the removeDomain resource. The name must
163 match exactly; xdm is not aware of all the network aliases that might
164 reach a given display. If the name resolve fails, the address is used.
165 The resource class is as sent by the display in the XDMCP Manage re‐
166 quest.
167 Because the resource manager uses colons to separate the name of the
169 resource from its value and dots to separate resource name parts, xdm
170 substitutes underscores for both dots and colons when generating the
171 resource name. For example, DisplayManager.expo_x_org_0.startup is the
172 name of the resource which defines the startup shell file for the
173 ``expo.x.org:0'' display.
174 DisplayManager.servers
176 This resource either specifies a file name full of server en‐
177 tries, one per line (if the value starts with a slash), or a
178 single server entry. See the section Local Server Specification
179 for the details.
180 DisplayManager.requestPort
182 This indicates the UDP port number which xdm uses to listen for
183 incoming XDMCP requests. Unless you need to debug the system,
184 leave this with its default value of 177.
185 DisplayManager.errorLogFile
187 Error output is normally directed at the system console. To re‐
188 direct it, set this resource to a file name. A method to send
189 these messages to syslog should be developed for systems which
190 support it; however, the wide variety of interfaces precludes
191 any system-independent implementation. This file also contains
192 any output directed to stderr by the Xsetup, Xstartup, Xsession
193 and Xreset files, so it will contain descriptions of problems in
194 those scripts as well.
195 DisplayManager.debugLevel
197 If the integer value of this resource is greater than zero,
198 reams of debugging information will be printed. It also dis‐
199 ables daemon mode, which would redirect the information into the
200 bit-bucket, and allows non-root users to run xdm, which would
201 normally not be useful.
202 DisplayManager.daemonMode
204 Normally, xdm attempts to make itself into a daemon process
205 unassociated with any terminal. This is accomplished by forking
206 and leaving the parent process to exit, then closing file de‐
207 scriptors and releasing the controlling terminal. In some envi‐
208 ronments this is not desired (in particular, when debugging).
209 Setting this resource to ``false'' will disable this feature.
210 DisplayManager.pidFile
212 The filename specified will be created to contain an ASCII rep‐
213 resentation of the process-id of the main xdm process. Xdm also
214 uses file locking on this file to attempt to eliminate multiple
215 daemons running on the same machine, which would cause quite a
216 bit of havoc.
217 DisplayManager.lockPidFile
219 This is the resource which controls whether xdm uses file lock‐
220 ing to keep multiple display managers from running amok. On
221 System V, this uses the lockf library call, while on BSD it uses
222 flock.
223 DisplayManager.authDir
225 This names a directory under which xdm stores authorization
226 files while initializing the session. The default value is
227 /var/lib/xdm. Can be overridden for specific displays by Dis‐
228 playManager.DISPLAY.authFile.
229 DisplayManager.autoRescan
231 This boolean controls whether xdm rescans the configuration,
232 servers, access control and authentication keys files after a
233 session terminates and the files have changed. By default it is
234 ``true.'' You can force xdm to reread these files by sending a
235 SIGHUP to the main process.
236 DisplayManager.removeDomainname
238 When computing the display name for XDMCP clients, the name re‐
239 solver will typically create a fully qualified host name for the
240 terminal. As this is sometimes confusing, xdm will remove the
241 domain name portion of the host name if it is the same as the
242 domain name of the local host when this variable is set. By de‐
243 fault the value is ``true.''
244 DisplayManager.keyFile
246 XDM-AUTHENTICATION-1 style XDMCP authentication requires that a
247 private key be shared between xdm and the terminal. This re‐
248 source specifies the file containing those values. Each entry
249 in the file consists of a display name and the shared key.
250 DisplayManager.accessFile
252 To prevent unauthorized XDMCP service and to allow forwarding of
253 XDMCP IndirectQuery requests, this file contains a database of
254 hostnames which are either allowed direct access to this ma‐
255 chine, or have a list of hosts to which queries should be for‐
256 warded to. The format of this file is described in the section
257 XDMCP Access Control.
258 DisplayManager.exportList
260 A list of additional environment variables, separated by white
261 space, to pass on to the Xsetup, Xstartup, Xsession, and Xreset
262 programs.
263 DisplayManager.randomDevice
265 A file to read 8 bytes from to generate the seed of authoriza‐
266 tion keys. The default is /dev/urandom . If this file cannot
267 be read, or if a read blocks for more than 5 seconds, xdm falls
268 back to using a checksum of DisplayManager.randomFile to gener‐
269 ate the seed.
270 DisplayManager.greeterLib
272 On systems that support a dynamically-loadable greeter library,
273 the name of the library. The default is
274 /usr/libexec/libXdmGreet.so.
275 DisplayManager.choiceTimeout
277 Number of seconds to wait for display to respond after user has
278 selected a host from the chooser. If the display sends an XDMCP
279 IndirectQuery within this time, the request is forwarded to the
280 chosen host. Otherwise, it is assumed to be from a new session
281 and the chooser is offered again. Default is 15.
282 DisplayManager.sourceAddress
284 Use the numeric IP address of the incoming connection on multi‐
285 homed hosts instead of the host name. This is to avoid trying to
286 connect on the wrong interface which might be down at this time.
287 DisplayManager.willing
289 This specifies a program which is run (as) root when an an XDMCP
290 BroadcastQuery is received and this host is configured to offer
291 XDMCP display management. The output of this program may be dis‐
292 played on a chooser window. If no program is specified, the
293 string Willing to manage is sent.
294 DisplayManager.DISPLAY.resources
296 This resource specifies the name of the file to be loaded by
297 xrdb as the resource database onto the root window of screen 0
298 of the display. The Xsetup program, the Login widget, and
299 chooser will use the resources set in this file. This resource
300 data base is loaded just before the authentication procedure is
301 started, so it can control the appearance of the login window.
302 See the section Authentication Widget, which describes the vari‐
303 ous resources that are appropriate to place in this file. There
304 is no default value for this resource, but
305 /etc/X11/xdm/Xresources is the conventional name.
306 DisplayManager.DISPLAY.chooser
308 Specifies the program run to offer a host menu for Indirect
309 queries redirected to the special host name CHOOSER.
310 /usr/libexec/chooser is the default. See the sections XDMCP
311 Access Control and Chooser.
312 DisplayManager.DISPLAY.xrdb
314 Specifies the program used to load the resources. By default,
315 xdm uses /usr/bin/xrdb.
316 DisplayManager.DISPLAY.setup
318 This specifies a program which is run (as root) before offering
319 the Login window. This may be used to change the appearance of
320 the screen around the Login window or to put up other windows
321 (e.g., you may want to run xconsole here). By default, no pro‐
322 gram is run. The conventional name for a file used here is
323 Xsetup. See the section Setup Program.
324 DisplayManager.DISPLAY.startup
326 This specifies a program which is run (as root) after the au‐
327 thentication process succeeds. By default, no program is run.
328 The conventional name for a file used here is Xstartup. See the
329 section Startup Program.
330 DisplayManager.DISPLAY.session
332 This specifies the session to be executed (not running as root).
333 By default, /usr/bin/xterm is run. The conventional name is
334 Xsession. See the section Session Program.
335 DisplayManager.DISPLAY.reset
337 This specifies a program which is run (as root) after the ses‐
338 sion terminates. By default, no program is run. The conven‐
339 tional name is Xreset. See the section Reset Program.
340 DisplayManager.DISPLAY.openDelay
342 DisplayManager.DISPLAY.openRepeat
344 DisplayManager.DISPLAY.openTimeout
346 DisplayManager.DISPLAY.startAttempts
348 DisplayManager.DISPLAY.reservAttempts
350 These numeric resources control the behavior of xdm when at‐
351 tempting to open intransigent servers. openDelay is the length
352 of the pause in seconds between successive attempts, openRepeat
353 is the number of attempts to make, openTimeout is the amount of
354 time to wait while actually attempting the open (i.e., the maxi‐
355 mum time spent in the connect(2) system call) and startAttempts
356 is the number of times this entire process is done before giving
357 up on the server. After openRepeat attempts have been made, or
358 if openTimeout seconds elapse in any particular attempt, xdm
359 terminates and restarts the server, attempting to connect again.
360 This process is repeated startAttempts times, at which point the
361 display is declared dead and disabled. Although this behavior
362 may seem arbitrary, it has been empirically developed and works
363 quite well on most systems. The bound reservAttempts is the
364 number of times a successful connect is allowed to be followed
365 by a fatal error. When reached, the display is disabled. The
366 default values are openDelay: 15, openRepeat: 5, openTimeout:
367 120, startAttempts: 4 and reservAttempts: 2.
368 DisplayManager.DISPLAY.pingInterval
370 DisplayManager.DISPLAY.pingTimeout
372 To discover when remote displays disappear, xdm occasionally
373 pings them, using an X connection and XSync calls. pingInterval
374 specifies the time (in minutes) between each ping attempt, ping‐
375 Timeout specifies the maximum amount of time (in minutes) to
376 wait for the terminal to respond to the request. If the termi‐
377 nal does not respond, the session is declared dead and termi‐
378 nated. By default, both are set to 5 minutes. If you fre‐
379 quently use X terminals which can become isolated from the man‐
380 aging host, you may wish to increase this value. The only worry
381 is that sessions will continue to exist after the terminal has
382 been accidentally disabled. xdm will not ping local displays.
383 Although it would seem harmless, it is unpleasant when the work‐
384 station session is terminated as a result of the server hanging
385 for NFS service and not responding to the ping.
386 DisplayManager.DISPLAY.terminateServer
388 This boolean resource specifies whether the X server should be
389 terminated when a session terminates (instead of resetting it).
390 This option can be used when the server tends to grow without
391 bound over time, in order to limit the amount of time the server
392 is run. The default value is ``false.''
393 DisplayManager.DISPLAY.userPath
395 Xdm sets the PATH environment variable for the session to this
396 value. It should be a colon separated list of directories; see
397 sh(1) for a full description. The default value is
398 ``/bin:/usr/bin:/usr/bin:/usr/ucb''.
399 DisplayManager.DISPLAY.systemPath
401 Xdm sets the PATH environment variable for the startup and reset
402 scripts to the value of this resource. The default for this re‐
403 source is ``/etc:/bin:/usr/bin:/usr/bin:/usr/ucb''. Note the
404 absence of ``.'' from this entry. This is a good practice to
405 follow for root; it avoids many common Trojan Horse system pene‐
406 tration schemes.
407 DisplayManager.DISPLAY.systemShell
409 Xdm sets the SHELL environment variable for the startup and re‐
410 set scripts to the value of this resource. It is /bin/sh by de‐
411 fault.
412 DisplayManager.DISPLAY.failsafeClient
414 If the default session fails to execute, xdm will fall back to
415 this program. This program is executed with no arguments, but
416 executes using the same environment variables as the session
417 would have had (see the section Session Program). By default,
418 /usr/bin/xterm is used.
419 DisplayManager.DISPLAY.grabServer
421 DisplayManager.DISPLAY.grabTimeout
423 To improve security, xdm grabs the server and keyboard while
424 reading the login name and password. The grabServer resource
425 specifies if the server should be held for the duration of the
426 name/password reading. When ``false,'' the server is ungrabbed
427 after the keyboard grab succeeds, otherwise the server is
428 grabbed until just before the session begins. The default is
429 ``false.'' The grabTimeout resource specifies the maximum time
430 xdm will wait for the grab to succeed. The grab may fail if
431 some other client has the server grabbed, or possibly if the
432 network latencies are very high. This resource has a default
433 value of 3 seconds; you should be cautious when raising it, as a
434 user can be spoofed by a look-alike window on the display. If
435 the grab fails, xdm kills and restarts the server (if possible)
436 and the session.
437 DisplayManager.DISPLAY.authorize
439 DisplayManager.DISPLAY.authName
441 authorize is a boolean resource which controls whether xdm gen‐
442 erates and uses authorization for the local server connections.
443 If authorization is used, authName is a list of authorization
444 mechanisms to use, separated by white space. XDMCP connections
445 dynamically specify which authorization mechanisms are sup‐
446 ported, so authName is ignored in this case. When authorize is
447 set for a display and authorization is not available, the user
448 is informed by having a different message displayed in the login
449 widget. By default, authorize is ``true,'' authName is ``MIT-
450 MAGIC-COOKIE-1,'' or, if XDM-AUTHORIZATION-1 is available,
451 ``XDM-AUTHORIZATION-1 MIT-MAGIC-COOKIE-1.''
452 DisplayManager.DISPLAY.authFile
454 This file is used to communicate the authorization data from xdm
455 to the server, using the -auth server command line option. It
456 should be kept in a directory which is not world-writable as it
457 could easily be removed, disabling the authorization mechanism
458 in the server. If not specified, a name is generated from Dis‐
459 playManager.authDir and the name of the display.
460 DisplayManager.DISPLAY.authComplain
462 If set to ``false,'' disables the use of the unsecureGreeting in
463 the login window. See the section Authentication Widget. The
464 default is ``true.''
465 DisplayManager.DISPLAY.resetSignal
467 The number of the signal xdm sends to reset the server. See the
468 section Controlling the Server. The default is 1 (SIGHUP).
469 DisplayManager.DISPLAY.termSignal
471 The number of the signal xdm sends to terminate the server. See
472 the section Controlling the Server. The default is 15
473 (SIGTERM).
474 DisplayManager.DISPLAY.resetForAuth
476 The original implementation of authorization in the sample
477 server reread the authorization file at server reset time, in‐
478 stead of when checking the initial connection. As xdm generates
479 the authorization information just before connecting to the dis‐
480 play, an old server would not get up-to-date authorization in‐
481 formation. This resource causes xdm to send SIGHUP to the
482 server after setting up the file, causing an additional server
483 reset to occur, during which time the new authorization informa‐
484 tion will be read. The default is ``false,'' which will work
485 for all MIT servers.
486 DisplayManager.DISPLAY.userAuthDir
488 When xdm is unable to write to the usual user authorization file
489 ($HOME/.Xauthority), it creates a unique file name in this di‐
490 rectory and points the environment variable XAUTHORITY at the
491 created file. It uses /tmp by default.
492
494 First, the xdm configuration file should be set up. Make a directory
495 (usually /etc/X11/xdm) to contain all of the relevant files.
496 Here is a reasonable configuration file, which could be named xdm-con‐
498 fig:
499 DisplayManager.servers: /etc/X11/xdm/Xservers
501 DisplayManager.errorLogFile: /var/log/xdm.log
502 DisplayManager*resources: /etc/X11/xdm/Xresources
503 DisplayManager*startup: /etc/X11/xdm/Xstartup
504 DisplayManager*session: /etc/X11/xdm/Xsession
505 DisplayManager.pidFile: /var/run/xdm-pid
506 DisplayManager._0.authorize: true
507 DisplayManager*authorize: false
508 Note that this file mostly contains references to other files. Note
511 also that some of the resources are specified with ``*'' separating the
512 components. These resources can be made unique for each different dis‐
513 play, by replacing the ``*'' with the display-name, but normally this
514 is not very useful. See the Resources section for a complete discus‐
515 sion.
516
518 The database file specified by the DisplayManager.accessFile provides
519 information which xdm uses to control access from displays requesting
520 XDMCP service. This file contains three types of entries: entries
521 which control the response to Direct and Broadcast queries, entries
522 which control the response to Indirect queries, and macro definitions.
523 The format of the Direct entries is simple, either a host name or a
525 pattern, which is distinguished from a host name by the inclusion of
526 one or more meta characters (`*' matches any sequence of 0 or more
527 characters, and `?' matches any single character) which are compared
528 against the host name of the display device. If the entry is a host
529 name, all comparisons are done using network addresses, so any name
530 which converts to the correct network address may be used. For pat‐
531 terns, only canonical host names are used in the comparison, so ensure
532 that you do not attempt to match aliases. Preceding either a host name
533 or a pattern with a `!' character causes hosts which match that entry
534 to be excluded.
535 To only respond to Direct queries for a host or pattern, it can be fol‐
537 lowed by the optional ``NOBROADCAST'' keyword. This can be used to
538 prevent an xdm server from appearing on menus based on Broadcast
539 queries.
540 An Indirect entry also contains a host name or pattern, but follows it
542 with a list of host names or macros to which indirect queries should be
543 sent.
544 A macro definition contains a macro name and a list of host names and
546 other macros that the macro expands to. To distinguish macros from
547 hostnames, macro names start with a `%' character. Macros may be
548 nested.
549 Indirect entries may also specify to have xdm run chooser to offer a
551 menu of hosts to connect to. See the section Chooser.
552 When checking access for a particular display host, each entry is
554 scanned in turn and the first matching entry determines the response.
555 Direct and Broadcast entries are ignored when scanning for an Indirect
556 entry and vice-versa.
557 Blank lines are ignored, `#' is treated as a comment delimiter causing
559 the rest of that line to be ignored, and `\newline' causes the newline
560 to be ignored, allowing indirect host lists to span multiple lines.
561 Here is an example Xaccess file:
563 #
565 # Xaccess - XDMCP access control file
566 #
567 #
569 # Direct/Broadcast query entries
570 #
571 !xtra.lcs.mit.edu # disallow direct/broadcast service for xtra
573 bambi.ogi.edu # allow access from this particular display
574 *.lcs.mit.edu # allow access from any display in LCS
575 *.deshaw.com NOBROADCAST # allow only direct access
577 *.gw.com # allow direct and broadcast
578 #
580 # Indirect query entries
581 #
582 %HOSTS expo.lcs.mit.edu xenon.lcs.mit.edu \
584 excess.lcs.mit.edu kanga.lcs.mit.edu
585 extract.lcs.mit.edu xenon.lcs.mit.edu #force extract to contact xenon
587 !xtra.lcs.mit.edu dummy #disallow indirect access
588 *.lcs.mit.edu %HOSTS #all others get to choose
589 If compiled with IPv6 support, multicast address groups may also be in‐
591 cluded in the list of addresses indirect queries are set to. Multicast
592 addresses may be followed by an optional / character and hop count. If
593 no hop count is specified, the multicast hop count defaults to 1, keep‐
594 ing the packet on the local network. For IPv4 multicasting, the hop
595 count is used as the TTL.
596 Examples:
598 rincewind.sample.net ff02::1 #IPv6 Multicast to ff02::1
600 #with a hop count of 1
601 ponder.sample.net CHOOSER 239.192.1.1/16 #Offer a menu of hosts
602 #who respond to IPv4 Multicast
603 #to 239.192.1.1 with a
604 #TTL of 16
605
607 For X terminals that do not offer a host menu for use with Broadcast or
608 Indirect queries, the chooser program can do this for them. In the
609 Xaccess file, specify ``CHOOSER'' as the first entry in the Indirect
610 host list. Chooser will send a Query request to each of the remaining
611 host names in the list and offer a menu of all the hosts that respond.
612 The list may consist of the word ``BROADCAST,'' in which case chooser
614 will send a Broadcast instead, again offering a menu of all hosts that
615 respond. Note that on some operating systems, UDP packets cannot be
616 broadcast, so this feature will not work.
617 Example Xaccess file using chooser:
619 extract.lcs.mit.edu CHOOSER %HOSTS #offer a menu of these hosts
621 xtra.lcs.mit.edu CHOOSER BROADCAST #offer a menu of all hosts
622 The program to use for chooser is specified by the DisplayManager.DIS‐
624 PLAY.chooser resource. For more flexibility at this step, the chooser
625 could be a shell script. Chooser is the session manager here; it is
626 run instead of a child xdm to manage the display.
627 Resources for this program can be put into the file named by Display‐
629 Manager.DISPLAY.resources.
630 When the user selects a host, chooser prints the host chosen, which is
632 read by the parent xdm, and exits. xdm closes its connection to the X
633 server, and the server resets and sends another Indirect XDMCP request.
634 xdm remembers the user's choice (for DisplayManager.choiceTimeout sec‐
635 onds) and forwards the request to the chosen host, which starts a ses‐
636 sion on that display.
637
639 The following configuration directive is also defined for the Xaccess
640 configuration file:
641 LISTEN interface [list of multicast group addresses]
643 interface may be a hostname or IP address representing a network
644 interface on this machine, or the wildcard * to represent all
645 available network interfaces.
646 If one or more LISTEN lines are specified, xdm only listens for XDMCP
648 connections on the specified interfaces. If multicast group addresses
649 are listed on a listen line, xdm joins the multicast groups on the
650 given interface.
651 If no LISTEN lines are given, the original behavior of listening on all
653 interfaces is preserved for backwards compatibility. Additionally, if
654 no LISTEN is specified, xdm joins the default XDMCP IPv6 multicast
655 group, when compiled with IPv6 support.
656 To disable listening for XDMCP connections altogther, a line of LISTEN
658 with no addresses may be specified, or the previously supported method
659 of setting DisplayManager.requestPort to 0 may be used.
660 Examples:
662 LISTEN * ff02::1 # Listen on all interfaces and to the
663 # ff02::1 IPv6 multicast group.
664 LISTEN 10.11.12.13 # Listen only on this interface, as long
665 # as no other listen directives appear in
666 # file.
667
669 The Internet Assigned Numbers Authority has has assigned
670 ff0X:0:0:0:0:0:0:12b as the permanently assigned range of multicast ad‐
671 dresses for XDMCP. The X in the prefix may be replaced by any valid
672 scope identifier, such as 1 for Interface-Local, 2 for Link-Local, 5
673 for Site-Local, and so on. (See IETF RFC 4291 or its replacement for
674 further details and scope definitions.) xdm defaults to listening on
675 the Link-Local scope address ff02:0:0:0:0:0:0:12b to most closely match
676 the old IPv4 subnet broadcast behavior.
677
679 The resource DisplayManager.servers gives a server specification or, if
680 the values starts with a slash (/), the name of a file containing
681 server specifications, one per line.
682 Each specification indicates a display which should constantly be man‐
684 aged and which is not using XDMCP. This method is used typically for
685 local servers only. If the resource or the file named by the resource
686 is empty, xdm will offer XDMCP service only.
687 Each specification consists of at least three parts: a display name, a
689 display class, a display type, and (for local servers) a command line
690 to start the server. A typical entry for local display number 0 would
691 be:
692 :0 Digital-QV local /usr/bin/X :0
694 The display types are:
696 local local display: xdm must run the server
698 foreign remote display: xdm opens an X connection to a running server
699 The display name must be something that can be passed in the -display
701 option to an X program. This string is used to generate the display-
702 specific resource names, so be careful to match the names (e.g., use
703 ``:0 Sun-CG3 local /usr/bin/X :0'' instead of ``localhost:0 Sun-CG3 lo‐
704 cal /usr/bin/X :0'' if your other resources are specified as ``Display‐
705 Manager._0.session''). The display class portion is also used in the
706 display-specific resources, as the class of the resource. This is use‐
707 ful if you have a large collection of similar displays (such as a cor‐
708 ral of X terminals) and would like to set resources for groups of them.
709 When using XDMCP, the display is required to specify the display class,
710 so the manual for your particular X terminal should document the dis‐
711 play class string for your device. If it doesn't, you can run xdm in
712 debug mode and look at the resource strings which it generates for that
713 device, which will include the class string.
714 When xdm starts a session, it sets up authorization data for the
716 server. For local servers, xdm passes ``-auth filename'' on the
717 server's command line to point it at its authorization data. For XDMCP
718 servers, xdm passes the authorization data to the server via the Accept
719 XDMCP request.
720
722 The Xresources file is loaded onto the display as a resource database
723 using xrdb. As the authentication widget reads this database before
724 starting up, it usually contains parameters for that widget:
725 xlogin*login.translations: #override\
727 Ctrl<Key>R: abort-display()\n\
728 <Key>F1: set-session-argument(failsafe) finish-field()\n\
729 <Key>Return: set-session-argument() finish-field()
730 xlogin*borderWidth: 3
731 xlogin*greeting: CLIENTHOST
732 #ifdef COLOR
733 xlogin*greetColor: CadetBlue
734 xlogin*failColor: red
735 #endif
736 Please note the translations entry; it specifies a few new translations
739 for the widget which allow users to escape from the default session
740 (and avoid troubles that may occur in it). Note that if #override is
741 not specified, the default translations are removed and replaced by the
742 new value, not a very useful result as some of the default translations
743 are quite useful (such as ``<Key>: insert-char ()'' which responds to
744 normal typing).
745 This file may also contain resources for the setup program and chooser.
747
749 The Xsetup file is run after the server is reset, but before the Login
750 window is offered. The file is typically a shell script. It is run as
751 root, so should be careful about security. This is the place to change
752 the root background or bring up other windows that should appear on the
753 screen along with the Login widget.
754 In addition to any specified by DisplayManager.exportList, the follow‐
756 ing environment variables are passed:
757 DISPLAY the associated display name
759 PATH the value of DisplayManager.DISPLAY.systemPath
760 SHELL the value of DisplayManager.DISPLAY.systemShell
761 XAUTHORITY may be set to an authority file
762 Note that since xdm grabs the keyboard, any other windows will not be
764 able to receive keyboard input. They will be able to interact with the
765 mouse, however; beware of potential security holes here. If Display‐
766 Manager.DISPLAY.grabServer is set, Xsetup will not be able to connect
767 to the display at all. Resources for this program can be put into the
768 file named by DisplayManager.DISPLAY.resources.
769 Here is a sample Xsetup script:
771 #!/bin/sh
773 # Xsetup_0 - setup script for one workstation
774 xcmsdb < /etc/X11/xdm/monitors/alex.0
775 xconsole -geometry 480x130-0-0 -notify -verbose -exitOnFail &
776
778 The authentication widget prompts the user for the username, password,
779 and/or other required authentication data from the keyboard. Nearly
780 every imaginable parameter can be controlled with a resource. Re‐
781 sources for this widget should be put into the file named by Display‐
782 Manager.DISPLAY.resources. All of these have reasonable default val‐
783 ues, so it is not necessary to specify any of them.
784 The resource file is loaded with xrdb(1) so it may use the substitu‐
786 tions defined by that program such as CLIENTHOST for the client host‐
787 name in the login message, or C pre-processor #ifdef statements to pro‐
788 duce different displays depending on color depth or other variables.
789 Xdm can be compiled with support for the Xft(3) library for font ren‐
791 dering. If this support is present, font faces are specified using
792 the resources with names ending in ``face'' in the fontconfig face for‐
793 mat described in the Font Names section of fonts.conf(5). If not, then
794 fonts are specified using the resources with names ending in ``font''
795 in the traditional X Logical Font Description format described in the
796 Font Names section of X(7).
797 xlogin.Login.width, xlogin.Login.height, xlogin.Login.x, xlogin.Login.y
799 The geometry of the Login widget is normally computed automati‐
800 cally. If you wish to position it elsewhere, specify each of
801 these resources.
802 xlogin.Login.foreground
804 The color used to display the input typed by the user.
805 xlogin.Login.face
807 The face used to display the input typed by the user when built
808 with Xft support. The default is ``Serif-18''.
809 xlogin.Login.font
811 The font used to display the input typed by the user when not
812 built with Xft support.
813 xlogin.Login.greeting
815 A string which identifies this window. The default is ``X Win‐
816 dow System.''
817 xlogin.Login.unsecureGreeting
819 When X authorization is requested in the configuration file for
820 this display and none is in use, this greeting replaces the
821 standard greeting. The default is ``This is an unsecure ses‐
822 sion''
823 xlogin.Login.greetFace
825 The face used to display the greeting when built with Xft sup‐
826 port. The default is ``Serif-24:italic''.
827 xlogin.Login.greetFont
829 The font used to display the greeting when not built with Xft
830 support.
831 xlogin.Login.greetColor
833 The color used to display the greeting.
834 xlogin.Login.namePrompt
836 The string displayed to prompt for a user name. Xrdb strips
837 trailing white space from resource values, so to add spaces at
838 the end of the prompt (usually a nice thing), add spaces escaped
839 with backslashes. The default is ``Login: ''
840 xlogin.Login.passwdPrompt
842 The string displayed to prompt for a password, when not using an
843 authentication system such as PAM that provides its own prompts.
844 The default is ``Password: ''
845 xlogin.Login.promptFace
847 The face used to display prompts when built with Xft support.
848 The default is ``Serif-18:bold''.
849 xlogin.Login.promptFont
851 The font used to display prompts when not built with Xft sup‐
852 port.
853 xlogin.Login.promptColor
855 The color used to display prompts.
856 xlogin.Login.changePasswdMessage
858 A message which is displayed when the users password has ex‐
859 pired. The default is ``Password Change Required''
860 xlogin.Login.fail
862 A message which is displayed when the authentication fails, when
863 not using an authentication system such as PAM that provides its
864 own prompts. The default is ``Login incorrect''
865 xlogin.Login.failFace
867 The face used to display the failure message when built with Xft
868 support. The default is ``Serif-18:bold''.
869 xlogin.Login.failFont
871 The font used to display the failure message when not built with
872 Xft support.
873 xlogin.Login.failColor
875 The color used to display the failure message.
876 xlogin.Login.failTimeout
878 The number of seconds that the failure message is displayed.
879 The default is 10.
880 xlogin.Login.logoFileName
882 Name of an XPM format pixmap to display in the greeter window,
883 if built with XPM support. The default is no pixmap.
884 xlogin.Login.logoPadding
886 Number of pixels of space between the logo pixmap and other ele‐
887 ments of the greeter window, if the pixmap is displayed. The
888 default is 5.
889 xlogin.Login.useShape
891 If set to ``true'', when built with XPM support, attempt to use
892 the X Non-Rectangular Window Shape Extension to set the window
893 shape. The default is ``true''.
894 xlogin.Login.hiColor, xlogin.Login.shdColor
896 Raised appearance bezels may be drawn around the greeter frame
897 and text input boxes by setting these resources. hiColor is the
898 highlight color, used on the top and left sides of the frame,
899 and the bottom and right sides of text input areas. shdColor
900 is the shadow color, used on the bottom and right sides of the
901 frame, and the top and left sides of text input areas. The de‐
902 fault for both is the foreground color, providing a flat appear‐
903 ance.
904 xlogin.Login.frameWidth
906 frameWidth is the width in pixels of the area around the greeter
907 frame drawn in hiColor and shdColor.
908 xlogin.Login.innerFramesWidth
910 innerFramesWidth is the width in pixels of the area around text
911 input areas drawn in hiColor and shdColor.
912 xlogin.Login.sepWidth
914 sepWidth is the width in pixels of the bezeled line between the
915 greeting and input areas drawn in hiColor and shdColor.
916 xlogin.Login.allowRootLogin
918 If set to ``false'', don't allow root (and any other user with
919 uid = 0) to log in directly. The default is ``true''. This
920 setting is only checked by some of the authentication backends
921 at this time.
922 xlogin.Login.allowNullPasswd
924 If set to ``true'', allow an otherwise failing password match to
925 succeed if the account does not require a password at all. The
926 default is ``false'', so only users that have passwords assigned
927 can log in.
928 xlogin.Login.echoPasswd
930 If set to ``true'', a placeholder character (echoPasswdChar)
931 will be shown for fields normally set to not echo, such as pass‐
932 word input. The default is ``false''.
933 xlogin.Login.echoPasswdChar
935 Character to display if echoPasswd is true. The default is
936 ``*''. If set to an empty value, the cursor will advance for
937 each character input, but no text will be drawn.
938 xlogin.Login.translations
940 This specifies the translations used for the login widget. Re‐
941 fer to the X Toolkit documentation for a complete discussion on
942 translations. The default translation table is:
943 Ctrl<Key>H: delete-previous-character()
945 Ctrl<Key>D: delete-character()
946 Ctrl<Key>B: move-backward-character()
947 Ctrl<Key>F: move-forward-character()
948 Ctrl<Key>A: move-to-begining()
949 Ctrl<Key>E: move-to-end()
950 Ctrl<Key>K: erase-to-end-of-line()
951 Ctrl<Key>U: erase-line()
952 Ctrl<Key>X: erase-line()
953 Ctrl<Key>C: restart-session()
954 Ctrl<Key>\\: abort-session()
955 <Key>BackSpace: delete-previous-character()
956 <Key>Delete: delete-previous-character()
957 <Key>Return: finish-field()
958 <Key>: insert-char()
959 The actions which are supported by the widget are:
961 delete-previous-character
963 Erases the character before the cursor.
964 delete-character
966 Erases the character after the cursor.
967 move-backward-character
969 Moves the cursor backward.
970 move-forward-character
972 Moves the cursor forward.
973 move-to-begining
975 (Apologies about the spelling error.) Moves the cursor to the
976 beginning of the editable text.
977 move-to-end
979 Moves the cursor to the end of the editable text.
980 erase-to-end-of-line
982 Erases all text after the cursor.
983 erase-line
985 Erases the entire text.
986 finish-field
988 If the cursor is in the name field, proceeds to the password
989 field; if the cursor is in the password field, checks the cur‐
990 rent name/password pair. If the name/password pair is valid,
991 xdm starts the session. Otherwise the failure message is dis‐
992 played and the user is prompted again.
993 abort-session
995 Terminates and restarts the server.
996 abort-display
998 Terminates the server, disabling it. This action is not acces‐
999 sible in the default configuration. There are various reasons
1000 to stop xdm on a system console, such as when shutting the sys‐
1001 tem down, when using xdmshell, to start another type of server,
1002 or to generally access the console. Sending xdm a SIGHUP will
1003 restart the display. See the section Controlling XDM.
1004 restart-session
1006 Resets the X server and starts a new session. This can be used
1007 when the resources have been changed and you want to test them
1008 or when the screen has been overwritten with system messages.
1009 insert-char
1011 Inserts the character typed.
1012 set-session-argument
1014 Specifies a single word argument which is passed to the session
1015 at startup. See the section Session Program.
1016 allow-all-access
1018 Disables access control in the server. This can be used when
1019 the .Xauthority file cannot be created by xdm. Be very careful
1020 using this; it might be better to disconnect the machine from
1021 the network before doing this.
1022 On some systems (OpenBSD) the user's shell must be listed in
1024 /etc/shells to allow login through xdm. The normal password and account
1025 expiration dates are enforced too.
1026
1028 The Xstartup program is run as root when the user logs in. It is typi‐
1029 cally a shell script. Since it is run as root, Xstartup should be very
1030 careful about security. This is the place to put commands which add
1031 entries to utmp or wtmp files, (the sessreg program may be useful
1032 here), mount users' home directories from file servers, or abort the
1033 session if logins are not allowed.
1034 In addition to any specified by DisplayManager.exportList, the follow‐
1036 ing environment variables are passed:
1037 DISPLAY the associated display name
1039 HOME the initial working directory of the user
1040 LOGNAME the user name
1041 USER the user name
1042 PATH the value of DisplayManager.DISPLAY.systemPath
1043 SHELL the value of DisplayManager.DISPLAY.systemShell
1044 XAUTHORITY may be set to an authority file
1045 WINDOWPATH may be set to the "window path" leading to the X server
1046 No arguments are passed to the script. Xdm waits until this script ex‐
1048 its before starting the user session. If the exit value of this script
1049 is non-zero, xdm discontinues the session and starts another authenti‐
1050 cation cycle.
1051 The sample Xstartup file shown here prevents login while the file
1053 /etc/nologin exists. Thus this is not a complete example, but simply a
1054 demonstration of the available functionality.
1055 Here is a sample Xstartup script:
1057 #!/bin/sh
1059 #
1060 # Xstartup
1061 #
1062 # This program is run as root after the user is verified
1063 #
1064 if [ -f /etc/nologin ]; then
1065 xmessage -file /etc/nologin -timeout 30 -center
1066 exit 1
1067 fi
1068 sessreg -a -l $DISPLAY -x /etc/X11/xdm/Xservers $LOGNAME
1069 /etc/X11/xdm/GiveConsole
1070 exit 0
1071
1073 The Xsession program is the command which is run as the user's session.
1074 It is run with the permissions of the authorized user.
1075 In addition to any specified by DisplayManager.exportList, the follow‐
1077 ing environment variables are passed:
1078 DISPLAY the associated display name
1080 HOME the initial working directory of the user
1081 LOGNAME the user name
1082 USER the user name
1083 PATH the value of DisplayManager.DISPLAY.userPath
1084 SHELL the user's default shell (from getpwnam)
1085 XAUTHORITY may be set to a non-standard authority file
1086 KRB5CCNAME may be set to a Kerberos credentials cache name
1087 WINDOWPATH may be set to the "window path" leading to the X server
1088 At most installations, Xsession should look in $HOME for a file .xses‐
1090 sion, which contains commands that each user would like to use as a
1091 session. Xsession should also implement a system default session if no
1092 user-specified session exists.
1093 An argument may be passed to this program from the authentication wid‐
1095 get using the `set-session-argument' action. This can be used to se‐
1096 lect different styles of session. One good use of this feature is to
1097 allow the user to escape from the ordinary session when it fails. This
1098 allows users to repair their own .xsession if it fails, without requir‐
1099 ing administrative intervention. The example following demonstrates
1100 this feature.
1101 This example recognizes the special ``failsafe'' mode, specified in the
1103 translations in the Xresources file, to provide an escape from the or‐
1104 dinary session. It also requires that the .xsession file be executable
1105 so we don't have to guess what shell it wants to use.
1106 #!/bin/sh
1108 #
1109 # Xsession
1110 #
1111 # This is the program that is run as the client
1112 # for the display manager.
1113 case $# in
1115 1)
1116 case $1 in
1117 failsafe)
1118 exec xterm -geometry 80x24-0-0
1119 ;;
1120 esac
1121 esac
1122 startup=$HOME/.xsession
1124 resources=$HOME/.Xresources
1125 if [ -f "$startup" ]; then
1127 exec "$startup"
1128 else
1129 if [ -f "$resources" ]; then
1130 xrdb -load "$resources"
1131 fi
1132 twm &
1133 xman -geometry +10-10 &
1134 exec xterm -geometry 80x24+10+10 -ls
1135 fi
1136 The user's .xsession file might look something like this example.
1138 Don't forget that the file must have execute permission.
1139 #! /bin/csh
1141 # no -f in the previous line so .cshrc gets run to set $PATH
1142 twm &
1143 xrdb -merge "$HOME/.Xresources"
1144 emacs -geometry +0+50 &
1145 xbiff -geometry -430+5 &
1146 xterm -geometry -0+50 -ls
1147
1149 Symmetrical with Xstartup, the Xreset script is run after the user ses‐
1150 sion has terminated. Run as root, it should contain commands that undo
1151 the effects of commands in Xstartup, updating entries in utmp or wtmp
1152 files, or unmounting directories from file servers. The environment
1153 variables that were passed to Xstartup are also passed to Xreset.
1154 A sample Xreset script:
1156 #!/bin/sh
1158 #
1159 # Xreset
1160 #
1161 # This program is run as root after the session ends
1162 #
1163 sessreg -d -l $DISPLAY -x /etc/X11/xdm/Xservers $LOGNAME
1164 /etc/X11/xdm/TakeConsole
1165 exit 0
1166
1168 Xdm controls local servers using POSIX signals. SIGHUP is expected to
1169 reset the server, closing all client connections and performing other
1170 cleanup duties. SIGTERM is expected to terminate the server. If these
1171 signals do not perform the expected actions, the resources DisplayMan‐
1172 ager.DISPLAY.resetSignal and DisplayManager.DISPLAY.termSignal can
1173 specify alternate signals.
1174 To control remote terminals not using XDMCP, xdm searches the window
1176 hierarchy on the display and uses the protocol request KillClient in an
1177 attempt to clean up the terminal for the next session. This may not
1178 actually kill all of the clients, as only those which have created win‐
1179 dows will be noticed. XDMCP provides a more sure mechanism; when xdm
1180 closes its initial connection, the session is over and the terminal is
1181 required to close all other connections.
1182
1184 Xdm responds to two signals: SIGHUP and SIGTERM. When sent a SIGHUP,
1185 xdm rereads the configuration file, the access control file, and the
1186 servers file. For the servers file, it notices if entries have been
1187 added or removed. If a new entry has been added, xdm starts a session
1188 on the associated display. Entries which have been removed are dis‐
1189 abled immediately, meaning that any session in progress will be termi‐
1190 nated without notice and no new session will be started.
1191 When sent a SIGTERM, xdm terminates all sessions in progress and exits.
1193 This can be used when shutting down the system.
1194 Xdm attempts to mark its various sub-processes for ps(1) by editing the
1196 command line argument list in place. Because xdm can't allocate addi‐
1197 tional space for this task, it is useful to start xdm with a reasonably
1198 long command line (using the full path name should be enough). Each
1199 process which is servicing a display is marked -display.
1200
1202 To add an additional local display, add a line for it to the Xservers
1203 file. (See the section Local Server Specification.)
1204 Examine the display-specific resources in xdm-config (e.g., DisplayMan‐
1206 ager._0.authorize) and consider which of them should be copied for the
1207 new display. The default xdm-config has all the appropriate lines for
1208 displays :0 and :1.
1209
1211 You can use xdm to run a single session at a time, using the 4.3 init
1212 options or other suitable daemon by specifying the server on the com‐
1213 mand line:
1214 xdm -server “:0 SUN-3/60CG4 local /usr/bin/X :0”
1215 Or, you might have a file server and a collection of X terminals. The
1217 configuration for this is identical to the sample above, except the
1218 Xservers file would look like
1219 extol:0 VISUAL-19 foreign
1220 exalt:0 NCD-19 foreign
1221 explode:0 NCR-TOWERVIEW3000 foreign
1222 This directs xdm to manage sessions on all three of these terminals.
1224 See the section Controlling Xdm for a description of using signals to
1225 enable and disable these terminals in a manner reminiscent of init(8).
1226
1228 One thing that xdm isn't very good at doing is coexisting with other
1229 window systems. To use multiple window systems on the same hardware,
1230 you'll probably be more interested in xinit.
1231
1233 /etc/X11/xdm/xdm-config
1234 the default configuration file
1235 $HOME/.Xauthority user authorization file where xdm stores keys for
1237 clients to read
1238 /usr/libexec/chooser
1240 the default chooser
1241 /usr/bin/xrdb the default resource database loader
1243 /usr/bin/X the default server
1245 /usr/bin/xterm the default session program and failsafe client
1247 /var/lib/xdm/A<display>-<suffix>
1249 the default place for authorization files
1250 /tmp/K5C<display> Kerberos credentials cache
1252
1254 X(7), xinit(1), xauth(1), xrdb(1), Xsecurity(7), sessreg(1),
1255 Xserver(1), xdmshell(8), fonts.conf(5).
1256 X Display Manager Control Protocol
1257 IETF RFC 4291: IP Version 6 Addressing Architecture.
1258
1260 Keith Packard, MIT X Consortium
1261X Version 11 xdm 1.1.14 XDM(8)