.TH xdm "" "" "X Utility"
.PC "X display manager with support for XDMCP"
\fBxdm [\-config \fIfile\^\fB] [\-nodaemon] [\-debug \fIlevel\^\fB] [\-error \fIlog_file\^\fB] [\-resources \fIres_file\^\fB]\fR
	\fB[\-server \fIserver_entry\^\fB] [\-session \fIprogram\^\fB]\fR
.PP
.HS
.SH Options:
.IC "\fB\-config \fIconfiguration_file\fR"
Name the configuration file, which specifies resources to control
the behavior of
.B xdm
.IC "\fB\-debug \fIdebug_level\fR"
Set the numeric value for the resource
.B DisplayManager.debugLevel
.IC "\fB\-error \fIerror_log_file\fR"
Set the value for the resource
.B DisplayManager.errorLogFile
.IC "\fB\-nodaemon\fR"
Set
.B false
as the value for the resource
.B DisplayManager.daemonMode
.IC "\fB\-resources \fIresource_file\fR"
Set the value for the resource
.B DisplayManager*resources
.IC "\fB\-server \fIserver_entry\fR"
Set the value for the resource
.B DisplayManager.servers
.IC "\fB\-session \fIsession_program\fR"
Set the value for the resource
.B DisplayManager*session
.IC "\fB\-udpPort \fIport_number\fR"
Set the value for the resource
.B DisplayManager.requestPort
.IC "\fB\-xrm \fIresource_specification\fR"
Specify an arbitrary resource, as in most X Toolkit applications
.HE
.B xdm
manages a collection of X displays,
which may be on the local host or remote servers.
.II XDMCP
.II "X Display Manager Control Protocol"
.II init
.II getty
.II login
The design of
.B xdm
was guided by the needs of X terminals as well as by the X Consortium standard
\fIX Display Manager Control Protocol\fR (XDCMP).
.B xdm
provides services similar to those provided by
.BR init ,
.BR getty ,
and 
.B login
on character terminals:
that is, prompting for login name and password,
authenticating the user, and running a session.
.PP
A
.I session
is defined by the lifetime of a particular process.
On the traditional character-based terminal world,
it would be the user's login shell; in the context of
.BR xdm ,
this 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,
.B xdm
typically uses a window manager or terminal
as the session manager, which means that
termination of this process terminates the user's session.
.PP
When the session is terminated,
.B xdm
resets the X server and (optionally) restarts the whole process.
.PP
When
.B xdm
receives an Indirect query via XDMCP, it can run a
.B 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.
.PP
Because
.B 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.
.B xdm
has many options, most of which have reasonable defaults.
Browse through the various sections of this entry,
pick and choose the things you want to change.
Pay particular attention to the section
.IR "Session Program" ,
which describes how to set up the style of session desired.
.SH "Typical Usage"
.B xdm
is designed to operate in such a wide variety of environments that the term
.I typical
is probably a misnomer.
.PP
First, setr up
.B xdm
configuration file.
Make a directory (under \*(CO, \fB/usr/X11/lib/xdm\fR)
to contain all of the relevant
files.
Here is a reasonable configuration file, which could be named
.BR xdm-config :
.DM
.ta 0.5i 3.25i
	DisplayManager.servers:	/usr/X11/lib/xdm/Xservers
	DisplayManager.errorLogFile:	/usr/X11/lib/xdm/xdm-errors
	DisplayManager*resources:	/usr/X11/lib/xdm/Xresources
	DisplayManager*startup:	/usr/X11/lib/xdm/Xstartup
	DisplayManager*session:	/usr/X11/lib/xdm/Xsession
	DisplayManager.pidFile:	/usr/X11/lib/xdm/xdm-pid
	DisplayManager._0.authorize:	true
	DisplayManager*authorize:	false
.DE
.PP
Note that this file simply contains references to other files.
Note also
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's name, but normally this is not very
useful.
See the \fBResources\fP section, below, for a complete discussion.
.PP
The first file,
.BR /usr/X11/lib/xdm/Xservers ,
contains the list of displays to manage that are not using XDMCP.
Most workstations have only one display, numbered 0, so the file
will look something like this:
.DM
	:0 Local local /usr/bin/X11/X :0
.DE
.PP
This runs
.B /usr/X11/bin/X11/X
on this display and manages a continuous cycle of sessions.
.PP
The file
.B /usr/X11/lib/xdm/xdm-errors
contain error messages from
.B xdm
and anything output to stderr by
.BR Xsetup ,
.BR Xstartup ,
.BR Xsession ,
or
.BR Xreset .
When you have trouble getting
.B xdm
to work, check this file to see if
.B xdm
has any clues to the trouble.
.PP
The next configuration entry,
.BR /usr/X11/lib/xdm/Xresources ,
is loaded onto the display by
.B xrdb
as a resource data base.
As the authentication widget reads this data base before it starts up,
it usually contains parameters for that widget:
.DM
.ta 0.5i 1.0i
	xlogin*login.translations: #override\e
		<Key>F1: set-session-argument(failsafe) finish-field()\en\e
		<Key>Return: set-session-argument() finish-field()
	xlogin*borderWidth: 3
	#ifdef COLOR
	xlogin*greetColor: CadetBlue
	xlogin*failColor: red
	#endif
.DE
.PP
Please note the translations entry:
it specifies a few new translations for the widget that
allow users to escape from the default session
(and avoid troubles that may occur in it).
Note that if
.B #override
is not specified, the default translations are removed and replaced
by the new value, not a very useful result as some of the default translations
are quite useful (such as
.BR "<Key>: insert-char ()" ,
which responds to normal typing).
.PP
The file
.B Xstartup
shown here simply prevents login while the file
.B /etc/nologin
exists.
As there is no provision for displaying any messages here
(no core X client displays files),
the user will probably be baffled by this behavior.
Thus, this is not a complete example, but
simply a demonstration of the available functionality.
.PP
Here is a sample
.B Xstartup
script:
.DM
.ta .5i 1i
	#!/bin/sh
	#
	# Xstartup
	#
	# This program is run as root after the user is verified
	#
	if [ \-f /etc/nologin ]; then
		exit 1
	fi
	exit 0
.DE
.PP
The most interesting script is
.BR Xsession .
This version recognizes the special
.I failsafe
mode, specified in the translations in the file
.BR resources ,
shown above, to provide an escape from the ordinary session:
.DM
.ta .5i 1i 1.5i
	#!/bin/sh
	#
	# Xsession
	#
	# This is the program that is run as the client
	# for the display manager.  This example is
	# quite friendly as it attempts to run a per-user
	# .xsession file instead of forcing a particular
	# session layout
	#
.DE
.DM	
	case $# in
	1)
		case $1 in
		failsafe)
			exec xterm \-geometry 80x24\-0\-0 \-ls
			;;
		esac
	esac
.DE
.DM	
	startup=$HOME/.xsession
	resources=$HOME/.Xresources
.DE
.DM	
	if [ \-f $startup ]; then
		exec $startup
		exec /bin/sh $startup
.DE
.DM
	else
		if [ ! \-f $resources ]; then
			resources=$HOME/.Xdefaults
		fi
		if [ \-f $resources ]; then
			xrdb \-load $resources
		fi
		twm &
		exec xterm \-geometry 80x24+10+10 \-ls
	fi
.DE
.SH Options
.B xdm
recognizes the following command-line options.
All of these options,
except
.BR \-config ,
specify values that can also be specified in the configuration file
as resources:
.IP "\fB\-config \fIconfiguration_file\fR"
Name the configuration file, which specifies resources to control
the behavior of
.BR xdm .
The default is
.BR /usr/X11/lib/xdm/xdm-config .
.IP "\fB\-debug \fIdebug_level\fR"
Set the numeric value for the resource
.BR DisplayManager.debugLevel .
A non-zero value causes
.B xdm
to print lots of debugging statements to the terminal;
it also disables the resource
.BR DisplayManager.daemonMode ,
which forces
.B xdm
to run synchronously.
To interpret these debugging messages, a copy of the source code for
.B xdm
is almost a necessity.
No attempt has been made to rationalize or standardize the output.
.IP "\fB\-error \fIerror_log_file\fR"
Set the value for the resource
.BR DisplayManager.errorLogFile .
This file contains errors from
.B xdm
as well as anything written to stderr by the various scripts and programs
run during the progress of the session.
.IP "\fB\-nodaemon\fR"
Set
.B false
as the value for the resource
.BR DisplayManager.daemonMode .
This suppresses the normal daemon behavior, which is for
.B xdm
to close all file descriptors, disassociate itself from
the controlling terminal, and put
itself in the background when it first starts up.
.IP "\fB\-resources \fIresource_file\fR"
Set the value for the resource
.BR DisplayManager*resources .
This file is loaded using
.B xrdb
to specify configuration parameters for the authentication widget.
.IP "\fB\-server \fIserver_entry\fR"
Set the value for the resource
.BR DisplayManager.servers .
See the section
.BR "Server Specification" ,
below, for a description of this resource.
.IP "\fB\-session \fIsession_program\fR"
Set the value for the resource
.BR DisplayManager*session .
This indicates the program to run as the session after the user has logged in.
.IP "\fB\-udpPort \fIport_number\fR"
Set the value for the resource
.BR DisplayManager.requestPort .
This sets the port-number that
.B xdm
monitor for XDMCP requests.
As XDMCP uses the registered well-known UDP port 177,
do not change this resource except for debugging.
.IP "\fB\-xrm \fIresource_specification\fR"
Specify an arbitrary resource, as in most X Toolkit applications.
.SH Resources
At many stages, you can control the actions of
.B xdm
by modifying its configuration file, which is in the
X resource format.
Some resources modify the behavior of
.B xdm
on all displays,
whereas others modify its behavior on a single display.
Where actions relate to a specific display,
the display name is inserted into the resource name between
.B DisplayManager
and the final resource-name segment.
For example,
.B DisplayManager.expo_0.startup
names the resource that defines the startup shell file on display
.BR expo:0 .
Because the resource manager uses colons to separate
the name of the resource from its value
and dots to separate resource name parts,
.B xdm
substitutes underscores for both dots and colons when generating the resource
name.
.IP "\fBDisplayManager.servers\fR"
This resource either names a file of server entries, one per
line (if its value begins with a slash), or a single server entry.
See the section \fBServer Specification\fR, below, for details.
.IP "\fBDisplayManager.requestPort\fR"
This indicates the UDP port number that
.B xdm
uses to listen for incoming XDMCP requests.
Unless you need to debug the system,
leave this with its default value of 177.
.IP "\fBDisplayManager.errorLogFile\fR"
.B xdm
normally directs error messages to the system's console.
To redirect error messages,
set this resource to name a file.
Error messages from scripts
.BR Xsetup ,
.BR Xstartup ,
.BR Xsession ,
and
.B Xreset
will also be redirected into this file.
.IP "\fBDisplayManager.debugLevel\fR"
If the integer value of this resource is greater than zero,
.B xdm
prints reams of debugging information.
It also disables daemon mode,
which would redirect the information into the bit-bucket,
and allows non-root users to run
.BR xdm ,
which normally is not useful.
.IP "\fBDisplayManager.daemonMode\fR"
.B xdm
normally attempts to make itself
into a daemon process unassociated with any terminal.
This is accomplished by forking and leaving the parent process to exit,
then closing file descriptors and releasing the controlling terminal.
In some environments, this is not desired (in particular, when debugging).
Setting this resource to
.B false
disables this feature.
.IP "\fBDisplayManager.pidFile\fR"
Set the file name into which
.B xdm
writes an ASCII representation of its process identifier.
.B xdm
uses this file as a locking file,
to attempt to prevent a machine from running multiple daemons,
which would cause quite a bit of havoc.
.IP "\fBDisplayManager.lockPidFile\fR"
Controls whether
.B xdm
uses file locking to stop a machine from running multiple
.B xdm
daemons.
Under \*(CO, it uses the general function
.BR lockf() .
.IP "\fBDisplayManager.authDir\fR"
Name the directory into which
.B xdm
writes authorization files while it initializes the session.
The default value is
.BR /usr/X11/lib/xdm .
.IP \fBDisplayManager.autoRescan\fR
Control whether
.B xdm
rescans the files that hold
configuration, servers, access control, and authentication keys
after a session terminates and the files have changed.
By default, this is
.BR true .
You can force
.B xdm
to reread these files by using the command
.B kill
to send the signal
.B SIGHUP
to the main process.
.IP "\fBDisplayManager.removeDomainname\fR"
When computing the display name for XDMCP clients, the name resolver will
typically create a fully qualified host name for the terminal.
As this is sometimes confusing,
.B xdm
removes the domain-name portion of the host name if it is the same as the
domain name of the local host when this variable is set.
By default, the value is
.BR true .
.IP "\fBDisplayManager.keyFile\fR"
XDM-AUTHENTICATION-1 style XDMCP authentication requires that a private key
be shared between
.B xdm
and the terminal.
This resource specifies the file containing those values.
Each entry in the file consists of a display name and the shared key.
.II DES
.II "Data Encryption Standard"
By default,
.B xdm
does not support XDM-AUTHENTICATION-1, as it requires the use
of the U.S. Department of Commerce's Data Encryption Standard (DES),
whose export is severely restricted by U.S. law.
.IP \fBDisplayManager.accessFile\fR
To prevent unauthorized XDMCP service and to allow forwarding of XDMCP
.B IndirectQuery
requests, this file contains the names of hosts to which your system
either permits direct access or possesses a list of hosts to
to which queries should be forwarded.
The format of this file is described in the section
.BR "XDMCP Access Control" ,
below.
.IP \fBDisplayManager.exportList\fR
This consists of a list of additional environmental variables
that are passed to the scripts
.BR Xsetup ,
.BR Xstartup ,
.BR Xsession ,
and
.BR Xreset .
.IP \fBDisplayManager.randomFile\fR
Names the file that holds the
checksum from which is generated the seed of authorization keys.
This should be a file that changes frequently.
The default is
.BR /dev/mem .
.IP "\fBDisplayManager.DISPLAY.resources\fR"
Name the file that
.B xrdb
loads onto the root window of screen 0 of the display
as the resource data base.
The program
.BR Xsetup ,
the Login widget, and the program
.B chooser
use the resources set in this file.
.B xdm
loads the data base named by this resource
just before it begins the authentication procedure
so the data base can control the appearance of the login window.
See the section
.BR "Authentication Widget" ,
below, which describes the various
resources that are appropriate to place in this file.
There is no default value for this resource, but
the conventional name is
.BR /usr/X11/lib/xdm/Xresources .
.IP "\fBDisplayManager.DISPLAY.chooser\fR"
Name the program that
.B xdm
runs to offer a host menu for Indirect queries
redirected to the special host name CHOOSER.
The default is
.BR /usr/X11/lib/xdm/chooser .
See the sections \fBXDMCP Access Control\fR and \fBChooser\fR, chooser.
.IP "\fBDisplayManager.DISPLAY.xrdb\fR"
Name the program that
.B xdm
uses to load the resources.
By default,
.B xdm
uses
.BR /usr/X11/bin/X11/xrdb .
.IP "\fBDisplayManager.DISPLAY.cpp\fR"
Name the C preprocessor that
.B xrdb
uses.
.IP "\fBDisplayManager.DISPLAY.setup\fR"
Name the program that
.B xdm
runs as root before it offers the Login window.
You can use this to change the appearence of the screen
around the Login window, or to display up other windows (e.g., you may wish
to run
.B xconsole
here).
By default, no program is run.
The conventional name for a file used here is
.BR Xsetup .
See the section entitled
.BR "Setup Program ,
below.
.IP "\fBDisplayManager.DISPLAY.startup\fR"
Name the program that
.B xdm
runs as root after the authentication process succeeds.
By default, no program is run.
The conventional name for a program used here is
.BR Xstartup .
See the section
.BR "Startup Program" ,
below.
.IP "\fBDisplayManager.DISPLAY.session\fR"
Name the session to execute (not running as root).
By default,
.B xdm
runs
.BR /usr/X11/bin/X11/xterm .
The conventional name is
.BR Xsession .
See the section
.BR "Session Program" ,
below.
.IP "\fBDisplayManager.DISPLAY.reset\fR"
Name the program that
.B xdm
runs as root after the session terminates.
Again, by default no program is run.
The conventional name is
.BR Xreset .
See the section
.BR "Reset Program" ,
below.
.IP "\fBDisplayManager.DISPLAY.openDelay\fR"
.IS "\fBDisplayManager.DISPLAY.openRepeat\fR"
.IS "\fBDisplayManager.DISPLAY.openTimeout\fR"
.IS "\fBDisplayManager.DISPLAY.startAttempts\fR"
These numeric resources control the behavior of
.B xdm
when it attempts to open intransigent servers.
.B openDelay
gives the number of seconds
.B xdm
pauses between attempts.
.B openRepeat
gives the number of attempts to make.
.B openTimeout
gives the amount of time
to wait while attempting the open, i.e., the maximum time spent in the
system call
.BR connect() .
.B startAttempts
gives the number of times this entire process
is performed before it gives up on the server.
.IP
After
.B openRepeat
attempts have been made,
or if
.B openTimeout
seconds elapse in any particular attempt,
.B xdm
terminates, restarts the server, and again attempts to connect.
.B xdm
repeats this process
.B startAttempts
times, at which point
.B xdm
declares that the display is dead and disables it.
.IP
Although this behavior appears arbitrary,
it has been empirically developed and works quite well on most systems.
The default values are five for
.BR openDelay ,
five for
.BR openRepeat ,
30 for
.BR openTimeout ,
and four for
.BR startAttempts .
.IP "\fBDisplayManager.DISPLAY.pingInterval\fR"
.IS "\fBDisplayManager.DISPLAY.pingTimeout\fR"
To discover when remote displays disappear,
.B xdm
occasionally pings them, using an X connection and calls to
.BR XSync .
.B pingInterval
gives the number of minutes between each ping attempt.
.B pingTimeout
gives the number of minutes to wait for the terminal to respond to the request.
If the terminal does not respond,
.B xdm
declares that the session is dead and terminates it.
By default, both are variables are set to five.
.IP
If you frequently use X terminals that
can become isolated from the managing host, you may wish to increase this value.
The only worry is that sessions will continue to exist after the
terminal has been disabled accidentally.
.B xdm
does not ping local displays.
Although it appears harmless, it is irritating when
.B xdm
terminates your workstation session because the
server's was hung for NFS service and did not respond to the ping.
.IP "\fBDisplayManager.DISPLAY.terminateServer\fR"
This Boolean resource specifies whether the X server should be terminated
instead of merely reset, when a session terminates.
Use this option when the server tends to grow without bound over time;
it will limit the time the server runs.
The default value is
.BR false .
.IP "\fBDisplayManager.DISPLAY.userPath\fR"
For this session,
.B xdm
sets the environmental variable
.B PATH
to this value.
It should be a colon-separated list of directories.
For a fuller description of a path, see the entry for
.B PATH
in the \*(CO Lexicon.
A common setting is:
.DM
	:/bin:/usr/bin:/usr/bin/X11:/usr/ucb
.DE
.IP
You can specify the default at build-time by setting the resource
.B DefaultUserPath
in the X system's configuration file.
.IP "\fBDisplayManager.DISPLAY.systemPath\fR"
.B xdm
sets to this resource the environmental variable
.B PATH
for the startup and reset scripts.
You can set the default for this resource
The resource
DefaultSystemPath
You can specify the default at build-time by setting the resource
.B DefaultSystemPath
in the X system's configuration file.
A common setting is:
.DM
	/etc:/bin:/usr/bin:/usr/bin/X11:/usr/ucb
.DE
.IP
Note the absence of `.' from this entry.
.II "trojan horse"
.II "security^trojan horse
This is a good practice to follow for
.BR root ;
it neutralizes many common trojan-horse system penetration schemes.
.IP "\fBDisplayManager.DISPLAY.systemShell\fR"
For the startup and reset scripts,
.B xdm
sets the environmental variable
.B SHELL
to this variable.
By default,
.B xdm
sets it to
.BR /bin/sh .
.IP "\fBDisplayManager.DISPLAY.failsafeClient\fR"
If the default session fails to execute,
.B xdm
falls back to this program.
It is executed with no arguments,
but executes using the same environment variables as
the session would have had.
(See the section
.BR "Session Program" ,
below).
By default,
.B xdm
uses
.BR /usr/X11/bin/X11/xterm\fR .
.IP "\fBDisplayManager.DISPLAY.grabServer\fR"
.IS "\fBDisplayManager.DISPLAY.grabTimeout\fR"
To improve security,
.B xdm
grabs the server and keyboard while it reads the login name and password.
.B grabServer
specifies whether the server should be held while
.B xdm
reads the user's login identifier and password.
When
.BR false ,
.B xdm
does not grab the server after it has succeeded in grabbing the keyboard;
otherwise it grabs the server until just before the session begins.
The default is
.BR false .
.B grabTimeout
gives the number of seconds
.B xdm
will wait for the grab to succeed.
The grab may fail if another client has grabbed the server,
or if the network latencies are very high.
This resource has a default value of three.
You should be cautious before you raise it, as a user can be spoofed by a
look-alike window on the display.
If the grab fails,
.B xdm
attempts to kill and restart the server, and then restart the session.
.IP "\fBDisplayManager.DISPLAY.authorize\fR"
.IS "\fBDisplayManager.DISPLAY.authName\fR"
\fBauthorize\fR is a Boolean resource that controls whether
.B xdm
generates and uses authorization for the local server connections.
If authorization is used,
.B authName
is a whitespace-separated list of authorization mechanisms to use.
XDMCP connections dynamically specify which
authorization mechanisms are supported, so
.B authName
is ignored in this case.
When
.B authorize
is set for a display and authorization is not available,
the user is informed by having a
different message displayed in the login widget.
By default,
.B authorize
is
.BR true ;
.B authName
is
.BR MIT-MAGIC-COOKIE-1 .
.IP \fBDisplayManager.DISPLAY.authFile\fR
This resource names the file that
.B xdm
uses to communicate the authorization data
to the server, using the server's command-line option
.BR \-auth .
Keep it in a directory that is not world-writable;
otherwise, someone could remove it and so disable the server's
authorization mechanism.
.IP "\fBDisplayManager.DISPLAY.authComplain\fR"
If this is set to
.BR false ,
.B xdm
disables the use of the
.B unsecureGreeting
in the login window.
See the section
.BR Authentication Widget ,
below.
The default is
.BR true .
.IP "\fBDisplayManager.DISPLAY.resetSignal\fR"
This gives the number of the signal that
.B xdm
uses to reset the server.
For details, see the section
.BR "Controlling the Server" ,
below.
The default is
.BR SIGHUP .
.IP "\fBDisplayManager.DISPLAY.termSignal\fR"
This gives the number of the signal that
.B xdm
sends to terminate the server.
For details, see the section
.BR "Controlling the Server" .
The default is
.BR SIGTERM .
.IP "\fBDisplayManager.DISPLAY.resetForAuth\fR"
Under the original implementation of its authorization mechanism,
the server re-read the authorization file when it (the server) was reset,
instead of when it checked the initial connection.
Because
.B xdm
generates the authorization information just before it connects to the
display, an old server would not get up-to-date authorization information.
This resource tells
.B xdm
to send
.B SIGHUP
to the server after it sets up the file.
This triggers an additional server reset,
which, in turn, compels the server to read the new authorization information.
The default is
.BR false ,
which works for all MIT servers.
.IP "\fBDisplayManager.DISPLAY.userAuthDir\fR"
When
.B xdm
cannot write to the usual user authorization file (\fB$HOME/.Xauthority\fR),
it creates a unique file name and points the environment
variable
.B XAUTHORITY
to it.
This resource names the directory into which
.B xdm
writes this file; the default is
.BR /tmp .
.SH "XDMCP Access Control"
The data-base file named by the resource
.B DisplayManager.accessFile
provides information that
.B xdm
uses to control access from displays requesting XDMCP service.
It contains the following three types of entries:
.IP \fBDirect\fR
A Direct entry consists of a host name or a pattern that
.B xdm
compares with the host name of the display device.
A pattern resembles a host name, except that it contains one or more
wildcard characters.
(For details on how to use wildcard characters, see the entry in the
\*(CO Lexicon for
.BR wildcards ).
If the entry is a host name,
.B xdm
performs all comparisons using network addresses,
so any name that converts to the correct network address may be used.
For patterns,
.B xdm
uses only canonical host names
in the comparison, so ensure that you do not attempt to match aliases.
Preceding either a host name or a pattern with a `!' character tells
.B xdm
to exclude any host that matches that entry.
.IP \fBIndirect\fR
An Indirect entry also contains a host name or pattern,
but follows it with a list of
host names or macros to which
.B xdm
should send indirect queries.
.IP \fBmacros\fR
A macro definition contains a macro name and a list of host names and
other macros into which the macro expands.
To distinguish macros from host names, macro names must begin with a
percent-sign character `%'.
Macros may be nested.
.PP
Indirect entries
may also specify to have
.B xdm
run
.B chooser
to offer a menu of hosts to which the user can connect.
For details, see the section
.BR Chooser ,
below.
.PP
When checking access for a particular display host,
.B xdm
scans each entry in turn, and selects the first entry that
matches what it is seeking.
.B xdm
ignores Direct and Broadcast entries when it scans for an Indirect entry,
and vice-versa.
.PP
.B xdm
ignores blank lines.
If a line contains a pound-sign character,
.B xdm
ignores all text from that character to the end of the line.
.PP
Preceeding a newline character with a backslash `\e' tells
.B xdm
to ignore the newline.
This allow a list of indirect host to span multiple lines.
.PP
The following gives an example
.B Xaccess
file:
.DM
#
# Xaccess \- XDMCP access control file
#
.DE
.DM
#
# Direct/Broadcast query entries
#
.DE
.DM
.ta 2.0i 4.0i
!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
.DE
.DM
#
# Indirect query entries
#
.DE
.DM
.ta 2.0i 4.0i
%HOSTS	expo.lcs.mit.edu xenon.lcs.mit.edu \\
	excess.lcs.mit.edu kanga.lcs.mit.edu
.DE
.DM
.ta 2.0i 4.0i
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
.DE
.SH Chooser
.B chooser
provides a host menu for use with Broadcast or Indirect queries.
It can be used on  X terminals that do not offer this on their own.
In the file
.BR Xaccess ,
specify
.B CHOOSER
as the first entry in the Indirect host list.
.B chooser
sends a Query request to each of the other hosts
named in the list, and offers a menu of all the hosts that respond.
.PP
The list of hosts may consist of the word
.BR BROADCAST ;
in this case,
.B chooser
sends a Broadcast, and then offers a menu of all hosts that respond.
Note that on some operating systems, UDP
packets cannot be broadcast, so this feature will not work.
.PP
The following gives an
example \fIXaccess\fR file that uses
.BR chooser :
.DM
extract.lcs.mit.edu	CHOOSER %HOSTS	#offer a menu of these hosts
xtra.lcs.mit.edu	CHOOSER BROADCAST	#offer a menu of all hosts
.DE
.PP
The program to use for
.B chooser
is specified by the resource
.BR DisplayManager.DISPLAY.chooser .
Resources for this program can be put into the file named by
.BR DisplayManager.DISPLAY.resources .
.SH "Server Specification"
The resource
.B DisplayManager.servers
gives a server specification.
If its value begins with a slash `/',
it names the file that contains server specifications, one per line.
.PP
Each specification describes a display that
.B xdm
must manage constantly and that does not use XDMCP.
Each consists of the following parts:
the name of the display, its class, its type,
and (for local servers) a command line to start the server.
The following gives a typical entry for local display 0:
.DM
	:0 Digital-QV local /usr/bin/X11/X :0
.DE
.PP
The following gives the types of displays:
.IP \fBlocal\fR 0.75i
Local display:
.B xdm
must run the server.
.IS \fBforeign\fR
Remote display:
.B xdm
opens an X connection to a running server.
.PP
The display name must be something that can be passed in the option
.B \-display
to an X program.
This string is used to generate the display-specific
resource names, so be careful to match the
names; e.g., use
.DM
	:0 local /usr/X11/bin/X11/X :0
.DE
.PP
instead of
.DM
	localhost:0 local /usr/X11/bin/X11/X :0
.DE
.PP
if your other resources are specified as
.BR 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 wish 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
.B xdm
in debug mode and
look at the resource strings which it generates for that device,
which will include the class string.
.SH "Setup Program"
.B xdm
runs the script
.B Xsetup
after it resets the server, but before it offers the Login window.
It is run as
.BR root ,
so should be careful to set its permissions properly.
This is the place to change the root background or bring up other
windows that should appear on the screen along with the Login widget.
.PP
In addition to any specified by the resource
.BR DisplayManager.exportList ,
.B xdm
passes the following environmental variables:
.IP \fBDISPLAY\fR 1.1i
The name of the associated display.
.IS \fBPATH\fR
The value of resource
.BR DisplayManager.DISPLAY.systemPath .
.IS \fBSHELL\fR
The value of resource
.BR DisplayManager.DISPLAY.systemShell .
.IS \fBXAUTHORITY\fR
An authority file, if any.
.PP
Because
.B xdm
grabs the keyboard, no other window can receive keyboard input;
however, they can interact with the mouse.
Beware of potential security holes here.
If the resource
.B DisplayManager.DISPLAY.grabServer
is set,
.B Xsetup
cannot connect to the display at all.
Resources for this program can be put into the file named by
.BR DisplayManager.DISPLAY.resources .
.SH "Authentication Widget"
The authentication widget reads a user's name and password from the keyboard.
Nearly every imaginable parameter can be controlled with a resource.
Place resources for this widget into the file named by the resource
.BR DisplayManager.DISPLAY.resources .
All of these have reasonable default values,
so it is not necessary to specify any of them:
.IP \fBxlogin.Login.width\fR
.IS \fBxlogin.Login.height\fR
.IS \fBxlogin.Login.x\fR
.IS \fBxlogin.Login.y\fR
These resources set the geometry of the Login widget.
This geometry normally is computed automatically.
If you wish to position it elsewhere, specify each of these resources.
.IP "\fBxlogin.Login.foreground\fR"
The color used to display the user's login identifier as she types it in.
.IP "\fBxlogin.Login.font\fR"
The font used to display the user's login identifier.
.IP "\fBxlogin.Login.greeting\fR"
A string that identifies this window.
The default is:
.DM
	X Window System
.DE
.IP "\fBxlogin.Login.unsecureGreeting\fR"
The standard greeting to use
when X authorization is requested in the configuration file for this
display and none is in use.
The default is:
.DM
	This is an unsecure session
.DE
.IP "\fBxlogin.Login.greetFont\fR"
The font used to display the greeting.
.IP "\fBxlogin.Login.greetColor\fR"
The color used to display the greeting.
.IP "\fBxlogin.Login.namePrompt\fR"
The string displayed to prompt for a user name.
.B xrdb
strips trailing white space from resource values, so to add spaces at
the end of the prompt (usually a nice thing), add spaces escaped with
backslashes.
The default is
.DM
	Login:
.DE
.IP "\fBxlogin.Login.passwdPrompt\fR"
The string displayed to prompt for a password.
The default is
.DM
	Password:
.DE
.IP "\fBxlogin.Login.promptFont\fR"
The font used to display both prompts.
.IP "\fBxlogin.Login.promptColor\fR"
The color used to display both prompts.
.IP "\fBxlogin.Login.fail\fR"
A message that
.B xdm
displays when authentication fails.
The default is
.DM
	Login incorrect
.DE
.IP "\fBxlogin.Login.failFont\fR"
The font used to display the failure message.
.IP "\fBxlogin.Login.failColor\fR"
The color used to display the failure message.
.IP "\fBxlogin.Login.failTimeout\fR"
The number of seconds that
.B xdm
displays the failure message.
The default is 30.
.IP "\fBxlogin.Login.translations\fR"
The translations used for the login widget.
Refer to the X Toolkit documentation for a complete discussion on translations.
The following gives default translation table:
.DM
.ta 0.5i 2.0i
	Ctrl<Key>H:	delete-previous-character() \en\e
	Ctrl<Key>D:	delete-character() \en\e
	Ctrl<Key>B:	move-backward-character() \en\e
	Ctrl<Key>F:	move-forward-character() \en\e
	Ctrl<Key>A:	move-to-begining() \en\e
	Ctrl<Key>E:	move-to-end() \en\e
	Ctrl<Key>K:	erase-to-end-of-line() \en\e
	Ctrl<Key>U:	erase-line() \en\e
	Ctrl<Key>X:	erase-line() \en\e
	Ctrl<Key>C:	restart-session() \en\e
	Ctrl<Key>\e\e:	abort-session() \en\e
	<Key>BackSpace:	delete-previous-character() \en\e
	<Key>Delete:	delete-previous-character() \en\e
	<Key>Return:	finish-field() \en\e
	<Key>:	insert-char() \e
.DE
.IP
The widget supports the following actions:
.RS
.IP "\fBdelete-previous-character\fR"
Erase the character before the cursor.
.IP "\fBdelete-character\fR"
Erase the character after the cursor.
.IP "\fBmove-backward-character\fR"
Move the cursor backward.
.IP "\fBmove-forward-character\fR"
Move the cursor forward.
.IP "\fBmove-to-begining\fR \fI(sic)\fR"
Move the cursor to the beginning of the editable text.
.IP "\fBmove-to-end\fR"
Move the cursor to the end of the editable text.
.IP "\fBerase-to-end-of-line\fR"
Erase all text after the cursor.
.IP "\fBerase-line\fR"
Erase the entire text.
.IP "\fBfinish-field\fR"
If the cursor is in the name field, proceed to the password field;
if the cursor is in the password field, check the current name/password pair.
If the name/password pair is valid,
.B xdm
starts the session.
Otherwise,
it displays the failure message and the user is prompted again to log in.
.IP "\fBabort-session\fR"
Terminate and restart the server.
.IP "\fBabort-display\fR"
Terminate the server, disabling it.
This is a rash action and
is not accessible in the default configuration.
You can use it to stop
.B xdm
when shutting the system down or when using
.BR xdmshell .
.IP "\fBrestart-session\fR"
Reset the X server and start a new session.
Use this when the resources have been changed and you want to test them,
or when the screen has been overwritten with system messages.
.IP "\fBinsert-char\fR"
Insert the character typed.
.IP "\fBset-session-argument\fR"
Specify a single-word argument that
.B xdm
passes to the session at startup.
For details, see the sections
.B "Session Program"
and
.B "Typical Usage" ,
below.
.IP "\fBallow-all-access\fR"
Disable access control in the server.
Use this when
.B xdm
cannot create the file
.BR .Xauthority .
Be very careful using this:
it may be better to disconnect the machine from the network before doing this.
.SH "Startup Program"
The script
.B Xstartup
must be run as
.BR root .
Therefore, be very careful to set its permissions correctly.
.PP
Put into this file
all commands that add entries to
.BR /etc/utmp ,
mount users' home directories from file servers,
display the message of the day,
or abort the session if logins are not allowed.
.PP
In addition to any by environemntal variables specified by the resource
.BR DisplayManager.exportList ,
.B Xstartup
passes the following environmental variables:
.IP \fBDISPLAY\fR 1.1i
The associated display name.
.IS \fBHOME\fR
The user's home directory.
.IS \fBUSER\fR
The user's login identifier.
.IS \fBPATH\fR
The value of resource
.BR DisplayManager.DISPLAY.systemPath .
.IS \fBSHELL\fR
The value of resource
.BR DisplayManager.DISPLAY.systemShell .
.IS \fBXAUTHORITY\fR
You can set this to an authority file.
.PP
.B xdm
passes no arguments to this script.
.B xdm
waits until this script exits before it starts the user's session.
If the exit value
.B Xstartup
is non-zero,
.B xdm
discontinues the session and starts another authentication cycle.
.SH "Session Program"
The program
.B Xsession
is the command that
.B xdm
runs as the user's session.
It is run with the user's permissions.
.PP
In addition to any specified by the resource
.BR DisplayManager.exportList ,
.B Xsession
passes the following environmental variables:
.IP \fBDISPLAY\fR
The name of the associated display.
.IS \fBHOME\fR
The user's home directory.
.IS \fBUSER\fR
The user's login identifier.
.IS \fBPATH\fR
The value of resource
.BR DisplayManager.DISPLAY.userPath .
.IS \fBSHELL\fR
The user's default shell, as obtained by the function
.BR getpwnam() .
.IS \fBXAUTHORITY\fR
You can set this to a non-standard authority file.
.PP
.II .xsession
At most installations,
.B Xsession
should look in
.B $HOME
for the file
.BR .xsession ,
which contains commands that the given user wishes like to use as a session.
.B Xsession
should also implement a system default session
if no user-specified session exists.
For details, see the section
.BR "Typical Usage" ,
below.
.PP
The authentication widget can use the action
.B set-session-argument
to pass an argument to this program.
.B Xsession
can use the argument to select different styles of session.
One good use of this feature is to allow
the user to escape from the ordinary session when it fails.
This allows a user to repair her
.B .xsession
if it fails, without requiring administrative intervention.
The section
.B "Typical Usage"
demonstrates this feature.
.SH "Reset Program"
Symmetrical with
.BR Xstartup ,
the script
.B Xreset
is run after the user session has terminated.
This script must be run as
.BR root ,
so be sure that its permissions are set correctly.
.PP
.B Xreset
contains commands that undo the effects of commands in
.BR Xstartup ,
remove entries from
.BR /etc/utmp ,
or unmount
directories from file servers.
The environment variables that were passed to
.B Xstartup
are also passed to
.BR Xreset .
.SH "Controlling the Server"
.B xdm
uses POSIX signals
to control local servers.
.B SIGHUP
resets the server;
the server should close all client connections and perform
other cleanup duties.
.B SIGTERM
terminates the server immediately.
If these signals fail to trigger the expected actions,
you can set the resources
.BR DisplayManager.DISPLAY.resetSignal
and
.B DisplayManager.DISPLAY.termSignal
to specify alternative signals.
.PP
To control remote terminals that do not use XDMCP,
.B xdm
searches the window hierarchy on the display and uses the protocol request
.B KillClient
to attempt to clean up the terminal for the next session.
This may not actually kill all of the clients,
as
.B xdm
notices only those that have created windows.
XDMCP provides a surer mechanism:
when
.B xdm
closes its initial connection, the session is over and the terminal is
required to close all other connections.
.SH "Controlling xdm"
.B xdm
responds to two signals
.B SIGHUP
and
.BR SIGTERM .
When sent
.BR SIGHUP ,
.B xdm
rereads the configuration file, the access control file, and the servers file.
For the servers file,
.B xdm
notices if entries have been added or removed.
If a new entry has been added,
.B xdm
starts a session on the associated display.
.B xdm
immediately disables all servers whose
entries that have been removed:
this means that any session in progress will be
terminated without notice and no new session will be started.
.PP
When sent a
.BR SIGTERM ,
.B xdm
terminates all sessions in progress and exits.
Use this when shutting down the system.
.PP
.B xdm
attempts to mark its various sub-processes for
.B ps
by editing the command-line argument list in place.
Because
.B xdm
can't allocate additional space for this task, it is useful to start
.B xdm
with a reasonably long command line
(using the full path name should be enough).
Each process which is servicing a display is marked
.BR \-\fR\fIdisplay .
.SH "Other Possibilities"
You can use
.B xdm
to run one session at a time, using options to the \*(CO process
.B init
or other suitable daemon, by specifying the server on the command line:
.DM
	xdm \-server ":0 SUN-3/60CG4 local /usr/bin/X :0"
.DE
.PP
You may also have a file server and a collection of X terminals.
The configuration for this is identical to the sample above,
except the script
.B Xservers
resembles the following:
.DM
	extol:0 VISUAL-19 foreign
	exalt:0 NCD-19 foreign
	explode:0 NCR-TOWERVIEW3000 foreign
.DE
.PP
This tells
.B xdm
to manage sessions on all three of these terminals.
For details, see the section
.BR "Controlling xdm" ,
above,
for a description of using signals to enable
and disable these terminals in a manner reminiscent of
.BR init .
Also see the entry for
.B init
in the \*(CO Lexicon.
.SH Limitations
.B xdm
does not coexist gracefully with other window systems.
To use multiple windowing systems on the same hardware,
you should use
.BR xinit .
.SH Files
\fB/usr/X11/lib/xdm/xdm-config\fR \(em The default configuration file
.br
\fB/usr/X11/lib/xdm/Xaccess\fR \(em The default access file
.br
\fB/usr/X11/lib/xdm/Xservers\fR \(em The default server file
.br
\fB$(HOME)/.Xauthority\fR \(em User-authorization file
.br
\fB/usr/X11/lib/xdm/chooser\fR \(em The default chooser
.br
\fB/usr/X11/bin/X11/xrdb\fR \(em The default resource data-base loader
.br
\fB/usr/X11/bin/X11/X\fR \(em The default server
.br
\fB/usr/X11/bin/X11/xterm\fR \(em Default session program and failsafe client
.br
\fB/usr/X11/lib/xdm/A\fIhost\fB\-\fIsuffix\fR \(em Default place for authorization files
.SH "See Also"
.B
xauth,
xinit,
X utilities
.R
.SH Notes
Copyright \(co 1988, Massachusetts Institute of Technology.
.PP
.II "Packard, Keith"
.B xdm
was written by Keith Packard of the MIT X Consortium.
