

***** THIS DOCUMENT IS NO LONGER MAINTAINED *****
***** Please read C/gdm.sgml                *****


The Gnome Display Manager

1. Theory of operation

gdm is a replacement for xdm, the X Display Manager. Unlike its
competitors (x3dm, kdm, wdm) gdm was written from scratch and does not
contain any original xdm code.

gdm was written with simplicity and security in mind. The overall
design concept is this:

When gdm starts it parses the config file gdm.conf. For each of the
local displays gdm forks a slave process. The main gdm process will
listen to XDMCP requests from remote displays and monitor the local
display sessions.

The gdm slave process starts an Xserver according to information read
from the config file. gdm sets up proper X authentication and starts
up the greeter window requesting the user for login and password. 

The gdm master and slave processes are deliberately kept small and
they are believed to be secure. The program providing the user
interface is significantly more complex and is linked to several
unaudited libraries. Therefore it runs as a dedicated gdm user and
communicates with gdm through a pipe.


2. Overview of the config directory.

The configuration files for gdm are located in the <prefix>/etc/gdm/
directory.

This is a listing of the config directory contents:

	Init/
	PostSession/
	PreSession/
	Sessions/
	gdm.conf

gdm.conf is the main gdm configuration file. The options will be
described later in this document.

The remaining configuration is done by dropping scripts in the
subdirectories of the gdm folder. This approach makes it easy for
package management systems to install window managers and different
session types without requiring the sysadmin/user to edit files.

In this section we will explain the Init, PreRoot and PostRoot
directories as they are very similar.

When the X server has been successfully started, gdm will try to run
the script called Init/<displayname>. I.e. Init/:0 for the first local
display.  If this file is not found, gdm will attempt to to run
Init/Default. The script will be run as root and gdm blocks until it
terminates. Use the Init/* script for programs that are supposed to
run alongside with the gdm login window. xconsole for
instance. Commands to set the background etc. goes in this file too.

It is up to the sysadmin to decide whether clients started by the Init
script should be killed before starting the user session. This is
controlled with the KillInitClient option in gdm.conf.

When the user has been successfully authenticated, gdm tries to run
the PreSession script. Similar to the Init-scripts,
PreSession/<displayname> will be executed first, if that is not found
gdm will attempt to run PreSession/Default. The script will be run as
root and gdm blocks until it terminates. Use this script for local
session management or accounting stuff. The USER environment variable
contains the login of the authenticated user. The script should return
0 on success. Any other value will cause gdm to terminate the current
login process.

Then the session script is run. Session scripts are located in the
etc/gdm/Session directory. Which one gdm runs depends on the session
the user chose in the Sessions-menu in the gdm greeter. If no session
is selected and the user has no last session stored in his
~/.gnome/gdm file, the system will choose or first script found or --
if Sessions/Default exists -- this will be run. For instance you can
create a symlink from Gnome to Default to make Gnome the default
desktop environment.

When the user terminates his session the PostSession script will be
run. Operation is similar to Init and PreSession. That is, gdm will
attempt to execute the script PostSession/<displayname> and if that
doesn't exist: PostSession/Default. Again the script will be run with
root priviledges, gdm will block and the USER environment variable
will contain the name of the user who just logged out.

Neither of the Init, PreSession or PostSession scripts are necessary
and can be left out. At least one session script is required for
proper operation.


3. The config file

3.1 Section: [daemon]

Chooser=@bindir@/gdmchooser --disable-sound
	Path and name of the gdmchooser executable.

DefaultPath=/bin:/usr/bin:/usr/bin/X11:/usr/local/bin
	Specifies the path which will be set in the user's session.

DisplayInitDir=@sysconfdir@/gdm/Init
	Directory containing the Init scripts.

Greeter=@bindir@/gdmlogin --disable-sound
	Path and name of the login program executable.

Group=gdm
	The group id under which gdmlogin/gdmchooser is run.

HaltCommand=/sbin/shutdown -h now
	Command to be executed when user selects Halt from the System
	menu (Full path to executable).

KillInitClients=1
	Determines whether gdm should kill X clients started by the
	Init scripts when the user logs in. Default is 1.

LogDir=@authdir@
	Directory containing the log files for the displays. By
	default this is the same as the ServAuthDir.

PidFile=/var/run/gdm.pid
	Name of the gdm daemon pidfile.

PostSessionScriptDir=@sysconfdir@/gdm/PostSession
	Directory containing the PostSession scripts.

PreSessionScriptDir=@sysconfdir@/gdm/PreSession
	Directory containing the PreSession scripts.

RebootCommand=/sbin/shutdown -r now
	Command to be executed when user selects Reboot from the
	System menu. Full path is required.

RootPath=/sbin:/usr/sbin:/bin:/usr/bin:/usr/bin/X11:/usr/local/bin
	Specifies the path which will be set in the root's session and
	the scripts executed by gdm.

ServAuthDir=@authdir@
	Directory containing the X authentication files for the
	displays. Should be owned by gdm.gdm with permissions 750.

SessionDir=@sysconfdir@/gdm/Sessions
	Directory containing the Session scripts.

User=gdm
	The username under which gdm is run.

UserAuthDir=
	The directory where user's .Xauthority file should be
	saved. When NULL ~user is used.

UserAuthFBDir=/tmp
	If gdm fails to update user's .Xauthority file for some odd
	reason a cookie is created in this directory.

UserAuthFile=.Xauthority
	Name of the file to store user cookies in.


3.2 Section: [security]

AllowRoot=0
	Set to 1 to enable root logins.

RelaxPermissions=0
	By default gdm ignores files/dirs writable to other users than
	the owner. 

	Changing the value of RelaxPermissions makes it possible to
	alter this behaviour:

	0 - Paranoia option. Only accepts user owned files and dirs.
	1 - Allow group writable files/dirs
	2 - Allow world writable files/dirs 

RetryDelay=3
	The number of seconds gdm should wait before reactivating the
	entry field after a failed login.

UserMaxFile=65536
	gdm will refuse to read/write files bigger than this number
	(in bytes).

	In addition to the size check both gdm and gdmlogin are
	extremely picky about accessing files in user directories.
	Neither will follow symlinks and they can optionally refuse to
	read files and directories writable by other than the owner.

VerboseAuth=0
	Specifies whether gdm should print authentication errors.
	Depending on authentication type usernames might be exposed
	when this option is on.


3.3 Section: [xdmcp]

Enable=0
	Setting to 1 enables XDMCP support allowing remote displays/X
	terminals to be managed by gdm.

	gdm listens for requests on UDP port 177. Access from remote
	displays is controlled by the TCP Wrappers library. The
	service name is `gdm'.

	You should add 

		gdm:	.my.domain

	or something similar to /etc/hosts.allow. See the
	hosts_access(5) man page for details.

	Please note that XDMCP is not a particularly secure protocol
	and that it is a good idea to block UDP port 177 on your
	firewall unless you really need it.

HonorIndirect=1
	Enables INDIRECT choosing (i.e. gdmchooser) for X-terminals
	which don't supply their own display browser.

MaxPending=4
	To avoid denial of service attacks, gdm has fixed size queue
	of pending connections. Only MaxPending displays can start at
	the same time. 

	Please note that this parameter does *not* limit the number of
	remote displays which can be managed. It only limits the
	number of simultaneous displays initiating a connection.

MaxPendingIndirect=4
	Specifies the number of remote displays that can be in choose
	mode simultaneously.

MaxSessions=16
	Determines the maximum number of remote display connections
	which will be accepted.

MaxWait=30
	When gdm is ready to manage a display an ACCEPT packet is sent
	to it containing a unique session id which will be used in
	future conversations.

	gdm will then place the session id in the pending queue
	waiting for the display to respond with a MANAGE request.

	If no response is received within MaxWait seconds, gdm
	will declare the display dead and erase it from the pending
	queue freeing up the slot for other displays.

MaxWaitIndirect=30
	FIXME

Port=177
	The UDP port number gdm should listen to for XDMCP requests.
	Don't change this.


3.4 Section: [gui]

Gtkrc=
	Path to a gtkrc containing the theme for use in
	gdmlogin/gdmchooser.

MaxIconWidth=128
MaxIconHeight=128
	Specifies the maximum icon sizes in the face browser.


3.5 Section: [greeter]

Browser=0
	Set to 1 to enable the face browser.

DefaultFace=@pixmapdir@/nophoto.png
	Default icon file for users without a personal picture in
	~/gnome/photo. The image must be in an Imlib supported format
	and it must be readable for the gdm user.

DefaultLocale=english
	This language is used for the user's session unless if nothing
	is specified in ~user/.gnome/gdm.

Exclude=bin,daemon,adm,lp,sync,shutdown,halt,mail,news,uucp,operator,nobody
	Comma-separated list of usernamed to exclude from the face
	browser.

Font=-adobe-helvetica-bold-r-normal-*-*-180-*-*-*-*-*-*
	Font to use for the welcome message.

GlobalFaceDir=@datadir@/faces/
	Systemwide directory for face files. The sysadmin can place
	icons for users here without touching their homedirs. The
	iconname represents a user name. I.e. <GlobalFaceDir>/johndoe
	would contain the icon for the user johndoe (No
	extension). The images must be in an Imlib supported format
	and they must be readable for the gdm user.

	A user's own icon file will take precedence over the sysadmin
	provided one.

Icon=@pixmapdir@/gdm.xpm
	File to use for gdmlogin when it's in iconified state. The
	image must be in an Imlib supported format and it must be
	readable for the gdm user. If no file is specified the
	iconify feature is disabled.

LocaleFile=@localedir@/locale.alias
	File in GNU locale format with entries for all supported
	languages. 

Logo=@pixmapdir@/gnome-logo-large.png
	File to display in the logo box. The image must be in an
	Imlib supported format and it must be readable for the gdm
	user. If no file is specified the logo feature is disabled.

Quiver=1
	Controls whether gdmgreeter should shake the display when an
	incorrect username/password is entered. Default: 1.

SystemMenu=0
	Turns the Shutdown/Halt menu on/off. Default: 0

Welcome=Welcome to %h
	Controls which text to display next to the logo image in the
	greeter. The following control chars are supported:

		%%	the `%' character
		%d	display's hostname
		%h	hostname
		%r	release (OS version)
		%s	sysname (i.e. OS)
		%m	machine (processor type)

3.6 Section: [chooser]

DefaultHostImage=@pixmapdir@/nohost.png
	File name for the default host icon.

HostImageDir=@datadir@/hosts
	Repository for host icon files. The sysadmin can place icons
	for remote hosts here and they will appear in gdmchooser.

	The file name must match the FQDN for the host (No extension!). 
	Icons must be in an Imlib supported format and must be
	readable to the gdm user.

ScanTime=3
	Specifies how many seconds gdmchooser should wait for replies
	to it's BROADCAST_QUERY. 


3.7 Section: [servers]


0=/usr/bin/X11/X
1=/usr/bin/X11/X -bpp 8

	Control section for local X servers. Each line indicates the
	local display number and which command needs to be run to
	start the X server(s).

	gdm will append "-auth <ServAuthDir>/:n.Xauth :n", where n is
	the display number, to this string.

$Id: gdm-manual.txt,v 1.7 1999/09/01 22:56:50 mkp Exp $
