path: root/docs/C/gdm.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
    <!ENTITY legal SYSTEM "legal.xml">
    <!ENTITY version "2.4.4.2"> 
    <!ENTITY date "9/18/2003"> 
]>

<article id="index" lang="en">
  <articleinfo>
    <title>Gnome Display Manager Reference Manual</title>
    <authorgroup>
      <author>
        <firstname>Martin</firstname><othername>K.</othername><surname>Petersen</surname>
        <affiliation>
          <address><email>mkp@mkp.net</email></address>
        </affiliation>
      </author>
      <author>
        <firstname>George</firstname><surname>Lebl</surname>
        <affiliation>
          <address><email>jirka@5z.com</email></address>
        </affiliation>
      </author>
      <author>
        <firstname>Brian</firstname><surname>Cameron</surname>
        <affiliation>
          <address><email>Brian.Cameron@Sun.COM</email></address>
        </affiliation>
      </author>
    </authorgroup>
    <copyright>
      <year>1998</year> <year>1999</year> <holder>Martin K. Petersen</holder>
    </copyright>
    <copyright>
      <year>2001</year> <holder>George Lebl</holder>
    </copyright>
    <copyright>
      <year>2003</year> <holder>Red Hat, Inc.</holder>
    </copyright>
    <copyright>
      <year>2003</year> <holder>Sun Microsystems, Inc.</holder>
    </copyright>

    &legal;

    <releaseinfo>
       This manual describes version &version; of the GNOME Display Manager. It was
       last updated on &date;.
    </releaseinfo>  
 
  </articleinfo>

  <sect1 id="preface">
    <title>Terms and Conventions Used in This Manual</title>

    <para>
       This manual describes version &version; of the GNOME Display Manager. It was
       last updated on &date;.
    </para>  

    <para>
      GDM - Gnome Display Manager. Used to describe the software
      package as a whole.
    </para>

    <para>
      gdm - The Gnome Display Manager daemon (<filename>gdm</filename>).
    </para>

    <para>
      Greeter - The graphical login window (<filename>gdmlogin</filename> or
      <filename>gdmgreeter</filename>).
    </para>

    <para>
      Standard Greeter - The standard login window (<filename>gdmlogin</filename>).
    </para>

    <para>
      Graphical Greeter - The themable login window (<filename>gdmgreeter</filename>).
    </para>

    <para>
      Chooser - The host chooser which appears on remote displays
      sending INDIRECT queries (<filename>gdmchooser</filename>).
    </para>

    <para>
      Configurator - The configuration program (<filename>gdmsetup</filename>).
    </para>

    <para>
      Paths without a leading '/' are relative to the installation
      prefix. I.e. <filename>share/pixmaps/</filename> refers to
      <filename>/usr/share/pixmaps</filename> if GDM was configured
      with <filename>--prefix=/usr</filename>.
    </para>

  </sect1>

  <sect1 id="overview">
    <title>Overview</title>

    <sect2 id="introduction">
      <title>
	Introduction
      </title>

      <para> 
	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 / X Consortium code. 
      </para>

      <para>
	For further information about GDM, see the
	<ulink type="http" url="http://www.jirka.org/gdm.html">
	the GDM website</ulink>.
      </para>

    </sect2>

    <sect2 id="daemonov">
      <title>The GDM Daemon</title>
      
      <para> 
	GDM was written with simplicity and security in mind. The
	overall design concept is this: 
      </para>
      
      <para> 
	Upon startup the <filename>gdm</filename> daemon parses its config file
	<filename>gdm.conf</filename>.  For each of the local displays <filename>gdm</filename>
	forks an Xserver and a slave process.  The main <filename>gdm</filename> process
	will then listen to XDMCP requests, if so configured, from remote displays and
	monitor the local display sessions.  The main daemon process will also allow
	starting of on new local Xservers on demand using the <filename>gdmflexiserver</filename>
	command.
      </para>
      
      <para> 
	The <filename>gdm</filename> slave process opens the display and starts
	<filename>gdmlogin</filename>, the graphical login
	program. <filename>gdmlogin</filename> runs as a dedicated
	user and communicates asynchronously with the slave process
	through a pipe.  Alternatively <filename>gdmgreeter</filename> command
	can be used which is the same as <filename>gdmlogin</filename> but
	allows greater themability.  <filename>gdmgreeter</filename>
	is referred to as the Graphical Greeter, while 
	<filename>gdmlogin</filename> is refereed to as the Standard
	Greeter.
      </para>
      
      <para> 
	GDM relies heavily on the presence of PAM, Pluggable
	Authentication Modules, but supports regular crypt() 
	and shadow passwords on legacy systems.
      </para>

      <para>
	Remote displays can connect to the XDMCP port on the GDM
	host. <filename>gdm</filename> will grant access to hosts specified in
	the gdm service section in your TCP Wrappers configuration
	file. GDM does not support remote display access control on
	systems without TCP Wrappers. XDMCP support can be turned off
	completely, however.
      </para>

      <para>
	GDM includes several measures making it more resistant to
	denial of service attacks on the XDMCP service. A lot of the
	protocol parameters, handshaking timeouts etc. can be fine
	tuned. The defaults should work for most systems, however.
	Don't change them unless you know what you're doing.
      </para>

      <para>
	In general GDM is very reluctant regarding reading/writing of
	user files. For instance it refuses to touch anything but
	regular files.  Links, sockets and devices are ignored.  The
	value of the RelaxPermissions parameter determines whether GDM
	should accept files writable by the user's group or others.
	These are ignored by default.
      </para>

      <para>
	All operations on user files are done with the effective
	user id of the user.  If the sanity check fails on the user's
	<filename>.Xauthority</filename> file, a fallback cookie is created in
	<filename>/tmp</filename>.
      </para>

      <para>
        Note that normally it is assumed that the home directory
	is only readable by the user.  However NFS traffic really
	goes "over the wire" and thus can be snooped.  For setups
	with NFS directories you should really use the
	<filename>UserAuthDir</filename> and set it to some local
	directory such as <filename>/tmp</filename>.  GDM will try
	to open the normal authorization file for reading as root, and
	if it fails, then 
	it will conclude that it is on an NFS mount and it will
	automatically use <filename>UserAuthFBDir</filename>,
	which is usually <filename>/tmp</filename>.
      </para>

      <para>
	GDM implements only the MIT-MAGIC-COOKIE-1 authorization scheme,
	see the XDMCP section for more information about this, especially
	relating to using X over the network.
      </para>

      <para>
	Finally, the sysadmin can specify the maximum file size GDM
	should accept, and, if the face browser is enabled, a tunable
	maximum icon size is also enforced.  On large systems it is
	still advised to turn off the face browser for performance
	reasons. Looking up icons in homedirs, scaling and rendering
	face icons can take quite a long time. YMMV.
      </para>

      <para>
	GDM also has a unix domain socket which can be used to control
	certain aspects of behavior, or to query information about running
	servers or logged in users.  This is the <filename>/tmp/.gdm_socket</filename>
	and the protocol is described in the sources in the
	<filename>daemon/gdm.h</filename> header file.  The
	<filename>gdmflexiserver</filename> command uses this for example to
	launch on demand X servers for the user.
      </para>

    </sect2>

    <sect2 id="displaytypes">
      <title>Different Display Types</title>

      <para>
	GDM allows 3 different display types.  First local static X servers.  These
	are always run, and when they die or are killed, they are restarted.  GDM
	can run as many of these as needed.  GDM can also manage servers on which it
	does not manage a login itself, thus allowing GDM to be used when building
	X terminals.
      </para>

      <para>
	Next GDM supports flexible or on demand servers.  These are run by
	requesting one using the socket protocol.  There is a command,
	<filename>gdmflexiserver</filename>, which can do this for the user. 
	For standard X servers the user must be logged in from a console, on
	one of the servers that GDM has run.  This command can however also
	launch nested <filename>Xnest</filename> servers which can be started
	even from non-console logins.  This is generally done by running
	<filename>gdmflexiserver -n</filename>.  These servers
	are not restarted when the user session ends.  
	<filename>gdmflexiserver</filename> normally also locks the users
	screen before running a new server with xscreensaver.
      </para>

      <para>
	Last display type is the XDMCP remote displays that are described
	in the next section.  Remote hosts can connect to GDM and present
	the login screen if this is enabled.  Some things may be different
	for these sessions, such as the Actions menu which allows you to
	shut down, reboot, or configure GDM will not be shown.
      </para>

    </sect2>

    <sect2 id="xdmcp">
      <title>
	XDMCP
      </title>

      <para>
	GDM also supports the X Display Manager Protocol (XDMCP) for
	managing remote displays.
      </para>

      <para>
	GDM listens to UDP port 177 and will respond to QUERY and
	BROADCAST_QUERY requests by sending a WILLING packet to the
	originator.
      </para>

      <para>
	GDM can also be configured to honor INDIRECT queries and
	present a host chooser to the remote display. GDM will
	remember the user's choice and forward subsequent requests to
	the chosen manager.  GDM also supports an extension to the
	protocol which will make it forget the redirection once
	the user's connection succeeds.  This extension is only
	supported if both daemons are GDM.  It is transparent and
	will be ignored by XDM or other daemons that implement
	XDMCP.
      </para>

      <para>
	GDM only supports the MIT-MAGIC-COOKIE-1 authentication
	system.  Normally little is gained from the other schemes,
	and no effort has been made to implement them so far.
	Because of this the cookies go over the wire as
	clear text, and thus you should be careful about what
	network you use this on.  If snooping is possible
	and undesirable, then you had better use ssh for tunneling
	an X connection anyway rather then using GDM's XDMCP.
      </para>

      <para>
	On the upside, GDM's random number generation is far superior
	to XDM or KDM.  At least the last time I looked at both of
	those.  XDM or KDM will only really have 31 bits of randomness
	for the MIT-MAGIC-COOKIE-1 (they both get a 31bit seed and then
	user a pseudorandom number generator to get 128 bits).  GDM goes
	to extraordinary measures to truly get a 128 bit random number,
	using hardware random number generators if available, plus the
	current time (in microsecond precision), a 20 byte array of pseudorandom
	numbers, process pid's, plus other random information (possibly using
	<filename>/dev/audio</filename> or <filename>/dev/mem</filename>)
	to create a large buffer and then run MD5.
	Obviously, all this work is wasted if you send this cookie over
	an open network or store it on an NFS directory (see
	<filename>UserAuthDir</filename> configuration key).
      </para>

      <para>
	Since it is fairly easy to do denial of service attacks on the
	XDMCP service, GDM incorporates a few features to guard
	against attacks. Please read the XDMCP reference section below
	for more information.
      </para>

      <para>
	Even though GDM tries to outsmart potential attackers, it is
	still advised that you block UDP port 177 on your firewall
	unless you really need it. GDM guards against DoS attacks, but
	the X protocol is still inherently insecure and should only be
	used in controlled environments.  Also each remote connection
	takes up lots of resources, so it is much easier to to DoS
	an XDMCP server.
      </para>

      <para>
	In addition to UDP port 177, you should also block all the
	X server ports (TCP ports 6000 + display number) on the firewall
	as well.  Do note that various places in GDM will use display
	numbers 20 and higher (for example the on demand server stuff).
	X is not a very safe protocol for leaving on the net, and XDMCP
	is even less safe.
      </para>

      <para>
	Even though your display is protected by cookies the XEvents
	and thus the keystrokes typed when entering passwords will
	still go over the wire in clear text. It is trivial to capture
	these.  You should also be aware that cookies, if placed on an
	NFS mounted directory, are prone to eavesdropping too.
	In case of NFS home directories you should really use the
	<filename>UserAuthDir</filename> and set it to some local
	temporary directory.
      </para>

      <para>
	XDMCP is primarily useful for running thin clients such
	as in terminal labs.  Those thin
	clients will only ever need to access the server, and so it seems
	like the best policy securitywise to have those thin clients on
	a separate network that cannot be accessed by the outside world,
	and can only connect to the server.  The only point from which you
	need to access outside is the server.
      </para>
    </sect2>

    <sect2 id="xdmcpaccess">
      <title>
	XDMCP Access Control
      </title>

      <para>
	XDMCP access control is done using TCP wrappers.  It is possible
	to compile GDM without TCP wrappers however, so you should test
	your configuration to see if they work.
      </para>

      <para>
	You should use the daemon name <filename>gdm</filename> in the
	<filename>/etc/hosts.allow</filename> and
	<filename>/etc/hosts.deny</filename> files.  For example to 
	deny computers from <filename>.evil.domain</filename> from logging in, then
	add
        <screen>
    gdm: .evil.domain</screen>
	to <filename>/etc/hosts.deny</filename>.  You may also need
	to add
        <screen>
    gdm: .your.domain</screen>
	to your <filename>/etc/hosts.allow</filename> if you normally
	disallow all services from all hosts.  See the
	<ulink type="help" url="man:hosts.allow">hosts.allow(5)</ulink> man page for details.
      </para>

      <para>
        Even though GDM now tries
	very hard to ignore things coming from banned hosts you should
	not rely on the TCP Wrappers for complete protection.  It is really
	best to block UDP port 177 (and all the X ports which are TCP ports
	6000 + the display number of course) on your firewall.
      </para>
    </sect2>

    <sect2 id="stdgreeter">
      <title>The Standard Greeter</title>

      <para>
	The Standard Greeter is the default graphical user interface that
	is presented to the user. The greeter contains a menu at the top, an
	optional face browser, an optional logo and a text entry
	widget.
      </para>

      <para>
        The text entry field is used for entering logins, passwords,
        passphrases etc. <filename>gdmlogin</filename> is controlled by the
        underlying daemon and is basically stateless. The daemon
        controls the greeter through a simple protocol where it can
        ask the greeter for a text string with echo turned on or
        off. Similarly, the daemon can change the label above the
        text entry widget to correspond to the value the
        authentication system wants the user to enter.
      </para>

      <para>
        The menu bar in the top of the greeter enables the user to
        select the requested session type/desktop environment,
        select an appropriate locale/language and optionally
        shutdown/reboot/suspend the machine, configure GDM (given the user
	knows the root password) or start an XDMCP chooser.
      </para>

      <para>
        Optionally the greeter can provide a face browser containing
	icons for all the users on a system. The icons can be installed globally
        by the sysadmin or in the users' home directories.  If installed
        globally they should be in the <filename>share/faces/</filename>
        directory (though this can be configured with the
        <filename>GlobalFaceDir</filename>
        configuration option) and the filename should be the name of
        the user, optionally with a <filename>.png</filename> appended.
      </para>

      <para>
        The users can place their icons in a file called <filename>~/.face</filename>,
        and they can use the program <filename>gdmphotosetup</filename> to
        graphically configure this.
      </para>
	
      <para>
        Face icons placed in the global face directory
        must be readable to the gdm user.  However, the daemon, proxies
        user pictures to the greeter and thus those don't have be be
        readable by the gdm user, but root.
      </para>

      <para>
        Please note that loading and scaling face icons located in
        user home directories can be a very time consuming task.
        Especially on large systems or systems running NIS. The
        browser feature is only intended for systems with relatively
        few users.  Also if home directories are on an on demand
	mounted filesystem like AFS, then GDM may mount all the
	home directories just to check for pictures if the face
	browser is on.  GDM will try to give up after 5 seconds of activity
	however and only display the users whoose pictures it
	has gotten so far.
      </para>

      <para>
        To filter out unwanted user names in the browser, an exclude
        option is implemented. The greeter will automatically ignore
        usernames listed in the <filename>Exclude</filename> statement in the
        config file, and furthermore exclude users whose UIDs are lower
	then <filename>MinimalUID</filename>.
      </para>

      <para>
        When the browser is turned on, valid usernames on the
        machine are inherently exposed to a potential intruder.
	This may be a bad idea if you don't know who can get to a login
	screen.  This is especially true if you run XDMCP.  However
	you should never run XDMCP on an open network anyway.
      </para>

      <para>
        The greeter can optionally display a logo in the login
        window. The image must be in a format readable to the gdk-pixbuf
        library (GIF, JPG, PNG, TIFF, XPM and possibly others), and
        it must be readable to the gdm user. See the
	<filename>Logo</filename> option in the reference section below
	for details.
      </para>

    </sect2>

    <sect2 id="graphgreeter">
      <title>The Graphical Greeter</title>

      <para>
	The Graphical Greeter is a greeter interface that takes up the whole
	screen and is very themable.  Themes can be selected and new themes
	can be installed by the Configuration program or by setting the
	<filename>GraphicalTheme</filename> configuration key.
      </para>

      <para>
	The look and feel of this greeter is really controlled by the theme and
	so the user interface elements that are present may be different.  The
	only thing that must always be present is the text entry field as described
	above in the Standard Greeter.
      </para>

      <para>
	You can always get a menu of available actions by pressing the F10 key.
	This can be useful if the theme doesn't provide certain buttons when you
	really wish to do some action.
      </para>

    </sect2>

    <sect2 id="logging">
      <title>Logging</title>

      <para>
	GDM itself will use syslog to log errors or status.  It can also 
	log debugging information, but this is not generally useful unless
	something is very wrong, and this must be enabled in the configuration
	file.
      </para>

      <para>
	Output from the various X servers is stored in the GDM log directory,	
	which is configurable, but is usually <filename>var/log/gdm/</filename>.
	The output from the session can be found in a file called
	<filename>&lt;display&gt;.log</filename>.  Four older files are
	also stored with <filename>.1</filename> through 
	<filename>.4</filename> appended.  These will be rotated as new
	sessions on that display are started.  You can use these logs
	to view what the X server said when it started up.
      </para>

      <para>
	The output from the user session is redirected to
	<filename>~/.xsession-errors</filename>
	before even the <filename>PreSession</filename> script is started.  So
	it is not really necessary to redirect this again in the session setup
	script.  As is usually done.  If the user session lasted less then
	10 seconds, GDM assumes that the session crashed and allows the user to
	view this file in a dialog before returning to the login screen.
	This way the user can view the session errors from
	the last session and correct the problem this way.
      </para>

      <para>
	The session output is piped through the GDM daemon and so the
	<filename>~/.xsession-errors</filename> file is capped at about
	200 kilobytes by GDM to prevent a possible denial of service attack
	on the session.  An app could perhaps on reading some wrong data print out
	warnings or errors on the stderr or stdout.  This could perhaps
	fill up the users home directory who would then have to log out and
	log back in to clear this.  This could be especially nasty if quotas
	are set.  GDM also correctly traps the XFSZ signal and stops writing
	the file, which would lead to killed sessions if the file was
	redirected in the old fashioned way from the script.
      </para>

      <para>
	Note that some distributors seem to
	override the <filename>~/.xsession-errors</filename> redirection and
	do it themselves in their own Xsession script (set by the
	<filename>BaseXsession</filename> configuration key) which means that
	GDM will not be able to trap the output and cap this file.  You also
	lose output from the <filename>PreSession</filename> script which can
	make debugging things harder to figure out as perhaps useful output
	of what is wrong will not be printed out.  See the description of the
	<filename>BaseXsession</filename> configuration key for more
	information, especially on how to handle multiple display managers
	using the same script.
      </para>

      <para>
	Note that if the session is a failsafe session, or if GDM can't open
	this file for some reason, then a fallback file will be created in the
	<filename>/tmp</filename> directory named
	<filename>/tmp/xses-&lt;user&gt;.XXXXXX</filename> where the
	<filename>XXXXXX</filename> are some random characters.
      </para>

      <para>
	If you run a system with quotas set, it would be good to delete the
	<filename>~/.xsession-errors</filename> in the
	<filename>PostSession</filename> script.  Such that this log file
	doesn't unneccesairly stay around.
      </para>

    </sect2>

    <sect2 id="gdmuser">
      <title>Security and the GDM User</title>

      <para>
	The GDM daemon normally runs as root, as does the slave.
	However GDM should also have a dedicated user id and a group
	id which it uses for its graphical interfaces such
	as <filename>gdmgreeter</filename> and <filename>gdmlogin</filename>.
	You can choose the name of this user and group in the
	<filename>[daemon]</filename> section of the configuration
	file.
      </para>

      <para>
	The GDM user, and group, which are normally just
	<filename>gdm</filename> should not be user or group of
	any particular privilage.  The reason for using them is
	to have the user interface run as a user without privilages
	so that in the unlikely case that someone finds a weakness
	in the GUI, they cannot access root on the machine.
      </para>

      <para>
	It should however be noted that the GDM user and
	group have some privilages that make them somewhat
	dangerous.  For one they have access to the server
	authorization directory (the <filename>ServAuthDir</filename>),
	which contains all the X server authorization files
	and other private information.  This means that
	someone who gains the GDM user/group privilages
	can then connect to any session.  So you should
	not, under any circumstances, make this some user/group
	which may be easy to get access to, such as the
	user <filename>nobody</filename>.
      </para>

      <para>
	The server authorization directory
	(the <filename>ServAuthDir</filename>) is used for
	a host of random internal data in addition to the
	X server authorization files, and the naming is really
	a relic of history.  GDM daemon enforces this dirctory
	to be owned by <filename>root.gdm</filename> with
	the permissions of 1770.  This way, only root and
	the GDM group have write access to this directory,
	but the GDM group cannot remove the root owned files
	from this directory, such as the X server authorization
	files.
      </para>

      <para>
	GDM by default doesn't trust the server authorization
	directory and treats it in the same way as the temporary
	directory with respect to creating files.  This way
	someone breaking the GDM user cannot mount attacks by
	creating links in this directory.  Similarly the X server
	log directory is treated safely, but that directory should
	really be owned and writable only by root.
      </para>

      <para>
	Anybody found not using a dedicated user for GDM
	should be whacked over the head with a large, blunt,
	heavy and rusty object, although the rusty requirement
	may be dropped if there is not enough time to have the
	object develop rust.
      </para>
    </sect2>
	  
  </sect1>

  <sect1 id="configuration">
    <title>Configuration</title>

    <para> 
      This section will cover the configuration of GDM
      and the format of the configuration file.  However you 
      can use the <filename>gdmsetup</filename> binary to configure
      GDM from a graphical environment.  The configuration program
      does not however let you configure every aspect of GDM however,
      so if the setup program does not cover your needs
      you may find information in this section.
    </para>

    <para>
      The configuration files, and especially the <filename>gdm.conf</filename>
      file, contain lots of useful comments, so also read these when
      changing your setup.
    </para>

    <para>
      Some keys in the configuration file as shipped are commented out
      while others are set.  This is done so that defaults can be easily
      changed in the future for some keys.  If you wish to set such a key
      you must first remove the leading hash mark that marks it as a
      comment.
    </para>

    <para> 
      The configuration files for GDM are located in the
      <filename>etc/gdm/</filename> directory.  And some which
      can be shared among other display managers are
      located in the <filename>etc/dm/</filename> directory.
    </para>

    <para>
      This is a listing of the config directory contents:
    </para>

    <screen>
	Init/
	PostLogin/
	PostSession/
	PreSession/
	modules/
	gdm.conf
	factory-gdm.conf
	locale.alias
	Xsession
	XKeepsCrashing
</screen>

    <para> 
      <filename>gdm.conf</filename> is the main GDM configuration file. The
      options will be described later in this section.
      <filename>factory-gdm.conf</filename> is the configuration file as shipped
      with the daemon.  This can be useful if you wish to revert to the default
      configuration.
    </para>

    <para> 
      <filename>locale.alias</filename> is a file which looks much like the
      system locale alias but in fact it is not the same.  These are the languages
      that are available on your system.  All the languages are still tested to
      see if they actually exist before presenting them to the user.
    </para>

    <para> 
      <filename>Xsession</filename> is a script which sets up a user session
      and then executes the users choice of session.
    </para>

    <para> 
      <filename>XKeepsCrashing</filename> is a script which gets run when the
      X server keeps crashing and we cannot recover.  The shipped default script
      will work with most Linux distributions and can run the X configuration
      program provided the person on the console knows the root password.
    </para>

    <para>
      <filename>gdm.conf</filename> is configuration file for both <filename>
      gdm</filename>, <filename>gdmgreeter</filename>, <filename>gdmlogin</filename>,
      and <filename>gdmchooser</filename> since a lot of parameters overlap.
    </para>

    <para>
      Accessibility modules are configured in the <filename>modules/</filename>
      subdirectory, and are a separate topic.
    </para>

    <para>
      The remaining configuration is done by dropping scripts in the
      subdirectories of the <filename>etc/gdm</filename> folder or
      dropping <filename>.desktop</filename> style files in
      <filename>etc/dm/Sessions</filename>. This
      approach makes it easy for package management systems to install
      window managers and different session types without requiring
      the sysadmin to edit files.
    </para>

    <sect2 id="scriptdirs">
      <title>The Script Directories</title>
      
      <para>
	In this section we will explain the <filename>Init</filename>,
	<filename>PostLogin</filename>,
	<filename>PreSession</filename> and <filename>PostSession</filename> directories as
	they are very similar.
      </para>

      <para>
	When the X server has been successfully started, GDM will try
	to run the script called
	<filename>Init/&lt;displayname&gt;</filename>. I.e. <filename>Init/:0</filename>
	for the first local display.  If this file is not found, GDM
	will attempt to to run
	<filename>Init/&lt;hostname&gt;</filename>. I.e. <filename>Init/somehost</filename>.
	If this still is not found, GDM will try
	<filename>Init/XDMCP</filename> for all XDMCP logins or
	<filename>Init/Flexi</filename> for all on demand flexible
	servers.  If none of the above were found, GDM will run
	<filename>Init/Default</filename>. The
	script will be run as root and GDM blocks until it
	terminates. Use the <filename>Init/*</filename> 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.
      </para>

      <para> 
	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 <filename>KillInitClients</filename>
	option in <filename>gdm.conf</filename>.
      </para>

      <para>
	When the user has been successfully authenticated GDM tries the
	scripts in the <filename>PostLogin</filename> directory in the
	same manner as for the <filename>Init</filename> directory.
	This is done before any session setup is done, and so this
	would be the script where you might setup the home directory
	if you need to (though you should use the
	<filename>pam_mount</filename> module if you can for this).
	You have the <filename>$USER</filename> and <filename>$DISPLAY</filename>
	environment variables set for this script,
	and again it is run as root.  The script should return 0 on success
	as otherwise the user won't be logged in.  This is not true for
	failsafe session however.
      </para>

      <para>
	After the user session has been setup from the GDM side of
	things, GDM will run the scripts in the <filename>PreSession</filename>
	directory, again in the same manner as the <filename>Init</filename>
	directory.  Use this
	script for local session management or accounting stuff. The
	<filename>$USER</filename> environment variable contains the login of the
	authenticated user and <filename>$DISPLAY</filename> is set to the current display.
	The script should return 0 on success.  Any
	other value will cause GDM to terminate the current login
	process.  This is not true for failsafe sessions however.
	Also <filename>$X_SERVERS</filename> environmental variable is set and this points
	to a fake generated x servers file for use with the
	sessreg accounting program.
      </para>

      <para>
	After this the base <filename>Xsession</filename> script is
	run with the selected session executable as the first argument.
	This is run as the user, and really this is the user session.
	The available session executables are taken from the
	<filename>Exec=</filename> line in the
	<filename>.desktop</filename> files in the
	<filename>etc/dm/Sessions</filename> directory.  The user
	either picks from these sessions or GDM will look inside
	the file <filename>~/.dmrc</filename> for the stored
	preference.
      </para>

      <para>
        This script should really load the users profile and generally
	do all the voodoo that is needed to launch a session.  Since
	many systems reset the language selections done by GDM, GDM
	will also set the <filename>$GDM_LANG</filename> variable to the selected language.
	You can use this to reset the language environmental
	variables after you run the users profile.  If the user
	elected to use the system language, then <filename>$GDM_LANG</filename>
	is not set. 
      </para>

      <para> 
	When the user terminates his session, the <filename>PostSession</filename> script
	will be run. Again operation is similar to <filename>Init</filename>,
	<filename>PostLogin</filename> and
	<filename>PreSession</filename>.
	Again the script will be run with root
	privileges, the slave daemon will block and the <filename>$USER</filename>
	environment variable will contain the name of the user who
	just logged out and <filename>$DISPLAY</filename> will be set to the display
	the user used, however note that the X server for this display
	may already be dead and so you shouldn't try to access it.
	Also <filename>$X_SERVERS</filename> environmental variable is set and this points
	to a fake generated x servers file for use with the
	sessreg accounting program.
      </para>

      <para>
	Note that the <filename>PostSession</filename> script will be run even when the
	display fails to respond due to an I/O error or similar. Thus,
	there is no guarantee that X applications will work during
	script execution.
      </para>

      <para>
	Except for the <filename>Xsession</filename> script all of these
	scripts will also have the environment variable
	<filename>$RUNNING_UNDER_GDM</filename> set to <filename>yes</filename>,
	so that you could perhaps use similar scripts for different display managers.
	The <filename>Xsession</filename> will always have the
	<filename>$GDMSESSION</filename> set to the basename of the
	session that the user chose to run without the <filename>.desktop</filename>
	extension.  In addition <filename>$DESKTOP_SESSION</filename> is also set
	to the same value and in fact this will also be set by KDM in future
	versions.
      </para>

      <para> 
	Neither of the <filename>Init</filename>, <filename>PostLogin</filename>,
	<filename>PreSession</filename> or <filename>PostSession</filename> scripts are
	necessary and can be left out.  The <filename>Xsession</filename> script
	is however required as well as at least one session <filename>.desktop</filename>
	file.
      </para>

    </sect2>

    <sect2 id="configfile">
      <title>The Configuration File - <filename>gdm.conf</filename></title>
      
      <para>
	The daemon and the accompanying utilities share a common
	configuration file: <filename>etc/gdm/gdm.conf</filename>.
      </para>

      <para>
	The configuration file is divided into sections each
	containing variables that define the behavior for a specific
	part of the GDM suite.  The file is fairly well commented
	as well.
      </para>

      <para>
	<filename>gdm.conf</filename> follows the standard <filename>.ini</filename>
	style configuration
	file syntax. Keywords in brackets define sections, strings
	before an equal sign (=) are variables and the data after
	equal sign represents their value.  Empty lines or lines
	starting with the hash mark (#) are ignored.  The
	graphical configurator will try to preserve both comments
	(lines with a hash mark) and the overall structure of the
	file so you can intermix using the GUI or hand editting the
	configuration file.
      </para>

      <sect3 id="daemonsection">
	<title>Daemon Configuration</title>

	<variablelist>
	  <title>[daemon]</title>

	  <varlistentry>
	    <term>AddGtkModules</term>
		<listitem>
	      <synopsis>AddGtkModules=false</synopsis>
	      <para>
	        If true, then enables gdmgreeter/gdmlogin to be launched with
		additional Gtk+ modules. This is useful when extra features are
		required such as accessible login. Note that only "trusted"
		modules should be used to minimize security issues.
              </para>
              <para>
		Usually this is used for accessibility modules.  The modules
		which are loaded are specified with the
		<filename>GtkModulesList</filename> key.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>AlwaysRestartServer</term>
	    <listitem>
	      <synopsis>AlwaysRestartServer=false</synopsis>
	      <para>
		If true, then gdm never tries to reuse existing X servers by
		reinitializing them.  It will just kill the existing server and
		start over.  Normally, just reinitializing is a nicer way to go
		but if the X server memory usage keeps growing this may be
		a safer option.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>AutomaticLoginEnable</term>
	    <listitem>
	      <synopsis>AutomaticLoginEnable=false</synopsis>
	      <para>
	 	If the user given in AutomaticLogin should be logged in upon
		first bootup.  No password will be asked.  This is useful
		for single user workstations where local console security
		is not an issue.  Also could be useful for public terminals,
		although there see <filename>TimedLogin</filename>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>AutomaticLogin</term>
	    <listitem>
	      <synopsis>AutomaticLogin=</synopsis>
	      <para>
		This user should be automatically logged in on first bootup.
		AutomaticLoginEnable must be true and this must be
		a valid user for this to happen.  "root" can never be
		autologged in however and gdm will just refuse to do it even
		if you set it up.
	      </para>

              <para>
                The following control chars are recognized within the specified name:
              </para>

              <para>
                &percnt;&percnt; &mdash; the `&percnt;' character
              </para>

              <para>
                &percnt;d &mdash; display's name
              </para>

              <para>
                &percnt;h &mdash; display's hostname
              </para>

              <para>
                Alternatively, the name may end with a vertical bar |, the pipe symbol.
                The name is then used as a program to execute which returns the desired
                username on standard output. If an empty or otherwise invalid username
                is returned, automatic login is not performed. This feature is typically
                used when several remote displays are used as internet kiosks, with a
                specific user to automatically login for each display.
              </para>
            </listitem>
          </varlistentry>

	  <varlistentry>
	    <term>BaseXsession</term>
	    <listitem>
	      <synopsis>BaseXsession=etc/gdm/Xsession</synopsis>
	      <para>
		This is the base X session file.  When a user logs in, this script
		will be run with the selected session as the first argument.  The
		selected session will be the <filename>Exec=</filename> from
		the <filename>.desktop</filename> file of the session.
	      </para>

              <para>
		If you wish to use the same script for several different display
		managers, and wish to have some of the script run only for GDM, then
		you can check the presence of the <filename>GDMSESSION</filename>
		environmental variable.  This will always be set to the basename of
		<filename>.desktop</filename> (without the extension) file that is
		being used for this
		session, and will only be set for GDM sessions.  Previously some
		scripts were checking for <filename>GDM_LANG</filename>, but that
		is only set when the user picks a non-system default language.
	      </para>

              <para>
		This script should take care of doing the "login" for the user
		and so it should source the <filename>/etc/profile</filename>
		and friends.  The standard script shipped with GDM sources
		the files in this order: <filename>/etc/profile</filename>
		then <filename>~/.profile</filename> then
		<filename>/etc/xprofile</filename> and finally
		<filename>~/.xprofile</filename>.  Note that different distributions
		may change this however.  Sometimes users personal setup will
		be in <filename>~/.bash_profile</filename>, however broken
		that is.
              </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>Chooser</term>
	    <listitem>
	      <synopsis>Chooser=bin/gdmchooser</synopsis>
	      <para>
		Full path and name of the chooser executable followed by optional arguments.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Configurator</term>
	    <listitem>
	      <synopsis>Configurator=bin/gdmsetup --disable-sound --disable-crash-dialog</synopsis>
	      <para>
		The pathname to the configurator binary.  If the greeter
		<filename>ConfigAvailable</filename> option is set to true then run this binary
		when somebody chooses Configuration from the Actions menu.
		Of course GDM will first ask for root password however.
		And it will never allow this to happen from a remote display.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>DefaultPath</term>
	    <listitem>
	      <synopsis>DefaultPath=/bin:/usr/bin:/usr/bin/X11:/usr/local/bin</synopsis>
	      <para>
		Specifies the path which will be set in the user's session.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>DefaultSession</term>
	    <listitem>
	      <synopsis>DefaultSession=gnome.desktop</synopsis>
	      <para>
		The session that is used by default if the user does not have
		a saved preference and has picked 'Last' from the list of
		sessions.  Note that 'Last' need not be displayed, see
		the <filename>ShowLastSession</filename> key.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  
	  <varlistentry>
	    <term>DisplayInitDir</term>
	    <listitem>
	      <synopsis>DisplayInitDir=etc/gdm/Init</synopsis>
	      <para>
		Directory containing the display init scripts. See the
		``The Script Directories'' section for more info.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>DoubleLoginWarning</term>
	    <listitem>
	      <synopsis>DoubleLoginWarning=true</synopsis>
	      <para>
		If true, GDM will warn the user if they are already logged in on
		another virtual terminal.  On systems where GDM supports checking
		the X virtual terminals, GDM will let the user switch to the
		previous login virtual terminal instead of logging in.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>FailsafeXServer</term>
	    <listitem>
	      <synopsis>FailsafeXServer=</synopsis>
	      <para>
		An X command line in case we can't start the normal X server.
		should probably be some sort of a script that runs an
		appropriate low resolution server that will just work.
		This is tried before the <filename>XKeepsCrashing</filename> script is run.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>FirstVT</term>
	    <listitem>
	      <synopsis>FirstVT=7</synopsis>
	      <para>
		On systems where GDM supports automatic VT (virtual terminal)
		allocation, this is the first vt to try.  Usually standard text
		logins are run on the lower vts.  See also <filename>VTAllocation</filename>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>FlexibleXServers</term>
	    <listitem>
	      <synopsis>FlexibleXServers=5</synopsis>
	      <para>
		The maximum number of allowed flexible servers.  These are
		servers that can be run using the
		<filename>/tmp/.gdm_socket</filename> socket
		connection.  This is used for both full servers and for
		Xnest servers.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Greeter</term>
	    <listitem>
	      <synopsis>Greeter=bin/gdmlogin</synopsis>
	      <para>
		Full path and name of the greeter executable followed by optional arguments.
		This is the greeter used for all servers except for the XDMCP remote servers.
		See also <filename>RemoteGreeter</filename>
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>Group</term>
	    <listitem>
	      <synopsis>Group=gdm</synopsis>
	      <para>
		The group name under which <filename>gdmlogin</filename>,
		<filename>gdmgreeter</filename>,
		<filename>gdmchooser</filename> and the internal
		failsafe GTK+ dialogs are run.  Also see <filename>User</filename>.
		This user will have access to all the X authorization files,
		and perhaps to other internal GDM data and it should not
		therefore be a user such as nobody, but rather a dedicated
		user.  The <filename>ServAuthDir</filename> is owned by this
		group.  The ownership and permissions of <filename>ServAuthDir</filename>
		should be <filename>root.gdm</filename> and 1770.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>GtkModulesList</term>
	    <listitem>
	      <synopsis>GtkModulesList=module-1:module-2:...</synopsis>
	      <para>
	    	A colon separated list of Gtk+ modules that gdmgreeter/gdmlogin
	    	will be invoked with if <filename>AddGtkModules</filename> is true. The format is the 
	    	same as the standard Gtk+ module interface.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>HaltCommand</term>
	    <listitem>
	      <synopsis>HaltCommand=/sbin/shutdown -h now</synopsis>
	      <para>
		Full path and arguments to command to be executed when
		user selects Shutdown from the Actions menu.  This can be a ';'
		separated list of commands to try.
		If a value is missing, the shutdown command is not available.
		Note that the default for this value is not empty so to
		disable shutdown you must set this explicitly to an empty
		value.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>KillInitClients</term>
	    <listitem>
	      <synopsis>KillInitClients=true</synopsis>
	      <para>
		Determines whether GDM should kill X clients started by
		the init scripts when the user logs in.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>LogDir</term>
	    <listitem>
	      <synopsis>LogDir=var/gdm</synopsis>
	      <para>
		Directory containing the log files for the individual
		displays.  By default this is the same as the
		ServAuthDir.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>PidFile</term>
	    <listitem>
	      <synopsis>PidFile=var/run/gdm.pid</synopsis>
	      <para>
		Name of the file containing the <filename>gdm</filename>
		process id.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>PostLoginScriptDir</term>
	    <listitem>
	      <synopsis>PostLoginScriptDir=etc/gdm/PostLogin</synopsis>
	      <para>
		Directory containing the scripts run right after the
		user logs in, but before any session setup is done.
		See the ``The Script Directories'' section for more info.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>PostSessionScriptDir</term>
	    <listitem>
	      <synopsis>PostSessionScriptDir=etc/gdm/PostSession</synopsis>
	      <para>
		Directory containing the scripts run after the user logs
		out.  See the ``The Script Directories'' section for more
		info.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>PreSessionScriptDir</term>
	    <listitem>
	      <synopsis>PreSessionScriptDir=etc/gdm/PreSession</synopsis>
	      <para>
		Directory containing the scripts run before the user
		logs in.  See the ``The Script Directories'' section for
		more info.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RebootCommand</term>
	    <listitem>
	      <synopsis>RebootCommand=/sbin/shutdown -r now</synopsis>
	      <para>
		Full path and optional arguments to the program to be
		executed when user selects Reboot from the Actions menu.
		This can be a ';' separated list of commands to try.
		If missing, the reboot command is not available.
		Note that the default for this value is not empty so to
		disable reboot you must set this explicitly to an empty
		value.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RemoteGreeter</term>
	    <listitem>
	      <synopsis>RemoteGreeter=bin/gdmlogin</synopsis>
	      <para>
		Full path and name of the greeter executable followed by optional arguments.  This
		is used for all remote XDMCP sessions.  It is useful to have the less 
		graphically demanding greeter here if you use the Graphical Greeter for your main
		greeter.
		See also the <filename>Greeter</filename> key.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RootPath</term>
	    <listitem>
	      <synopsis>RootPath=/sbin:/usr/sbin:/bin:/usr/bin:/usr/bin/X11:/usr/local/bin</synopsis>
	      <para>
		Specifies the path which will be set in the root's
		session and the {Init,PostLogin,PreSession,PostSession} scripts
		executed by GDM.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>ServAuthDir</term>
	    <listitem>
	      <synopsis>ServAuthDir=/var/gdm</synopsis>
	      <para>
		Directory containing the X authentication files for the
		individual displays.  Should be owned by
		<filename>root.gdm</filename> with permissions 1770,
		where <filename>gdm</filename> is the GDM group as defined
		by the <filename>Group</filename> option.
		That is should be owned by root, with <filename>gdm</filename> group having
		full write permissions and the directory should be
		sticky and others should have no permission to the directory.
		This way the gdm user can't remove files owned
		by root in that directory, while still being able to
		write its own files there.  GDM will attempt to change
		permissions for you when it's first run if the permissions
		are not the above.
		This directory is also used for other private files that
		the daemon needs to store.  Other users should not
		have any way to get into this directory and read/change
		it's contents.  Anybody who can read this directory can
		connect to any display on this machine.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>SessionDesktopDir</term>
	    <listitem>
	      <synopsis>SessionDesktopDir=etc/sessions:etc/dm/Sessions:/usr/share/X11/sessions</synopsis>
	      <para>
		Directory containing the <filename>.desktop</filename>
		files which are the available sessions on the system.
		Since 2.4.4.2 this is treated like a PATH type variable
		and the first file found is used.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>StandardXServer</term>
	    <listitem>
	      <synopsis>StandardXServer=/usr/bin/X11/X</synopsis>
	      <para>
		Full path and arguments to the standard X server command.
		This is used when gdm cannot find any other definition,
		and it's used as the default and failsafe fallback in a
		number of places.  This should be able to run some sort
		of X server.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>SuspendCommand</term>
	    <listitem>
	      <synopsis>SuspendCommand=</synopsis>
	      <para>
		Full path and arguments to command to be executed when
		user selects Suspend from the Actions menu.  If empty
		there is no such menu item.
		Note that the default for this value is not empty so to
		disable suspend you must set this explicitly to an empty
		value.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>TimedLoginEnable</term>
	    <listitem>
	      <synopsis>TimedLoginEnable=false</synopsis>
	      <para>
	 	If the user given in <filename>TimedLogin</filename> should be logged in after
		a number of seconds (set with <filename>TimedLoginDelay</filename>) of inactivity
		on the login screen.  This is useful for public access
		terminals or perhaps even home use.  If the user uses the
		keyboard or browses the menus, the timeout will be reset to
		<filename>TimedLoginDelay</filename> or 30 seconds, whichever is higher.  Note that
		no password will be asked for this user so you should be
		careful.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>TimedLogin</term>
	    <listitem>
	      <synopsis>TimedLogin=</synopsis>
	      <para>
		This is the user that should be logged in after a specified
		number of seconds of inactivity.  This can never be "root"
		and gdm will refuse to log in root this way.
		The same features as for <filename>AutomaticLogin</filename>
		are supported.  The same control chars and piping to a
		program are supported.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>TimedLoginDelay</term>
	    <listitem>
	      <synopsis>TimedLoginDelay=30</synopsis>
	      <para>
		This is the delay before the <filename>TimedLogin</filename> user will be logged
		in.  It must be greater then or equal to 10.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>User</term>
	    <listitem>
	      <synopsis>User=gdm</synopsis>
	      <para>
		The username under which <filename>gdmlogin</filename>,
		<filename>gdmgreeter</filename>,
		<filename>gdmchooser</filename> and the internal
		failsafe GTK+ dialogs are run.  Also see <filename>Group</filename>.
		This user will have access to all the X authorization files,
		and perhaps to other internal GDM data and it should not
		therefore be a user such as nobody, but rather a dedicated
		user.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>UserAuthDir</term>
	    <listitem>
	      <synopsis>UserAuthDir=</synopsis>
	      <para>
		The directory where user's
		<filename>.Xauthority</filename> file should be
		saved.  When nothing is specified the user's home
		directory is used.  This is tilde expanded so you
		can set it to things like: <filename>~/authdir/</filename>.
	      </para>

	      <para>
		If you do not use the tilde expansion, then
		the filename created will be random, like in
		<filename>UserAuthFBDir</filename>.  This way many
		users can have the same authentication directory.
		For example you might want to set this to
		<filename>/tmp</filename> when
		user has the home directory on NFS, since you really don't
		want cookie files to go over the wire.  The users should
		really have write privilages to this directory, and this
		directory should really be sticky and all that, just like
		the <filename>/tmp</filename> directory.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>UserAuthFBDir</term>
	    <listitem>
	      <synopsis>UserAuthFBDir=/tmp</synopsis>
	      <para>
		If GDM fails to update the user's
		<filename>.Xauthority</filename> file a
		fallback cookie is created in this directory.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>UserAuthFile</term>
	    <listitem>
	      <synopsis>UserAuthFile=.Xauthority</synopsis>
	      <para>
		Name of the file used for storing user cookies.  
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>VTAllocation</term>
	    <listitem>
	      <synopsis>VTAllocation=true</synopsis>
	      <para>
		On systems where GDM supports automatic VT (virtual terminal)
		allocation (currently Linux only), you can have GDM automatically append the vt argument
		to the X server executable.  This way races that come up from each X
		server managing it's own vt allocation can be avoided.
		See also <filename>FirstVT</filename>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>XKeepsCrashing</term>
	    <listitem>
	      <synopsis>XKeepsCrashing=etc/gdm/XKeepsCrashing</synopsis>
	      <para>
		A script to run in case X keeps crashing.  This is for running
		An X configuration or whatever else to make the X configuration
		work.  See the script that came with the distribution for an
		example.  The distributed <filename>XKeepsCrashing</filename> script is tested
		on Red Hat, but may work elsewhere.  Your system integrator should
		make sure this script is up to date for your particular system.
	      </para>
	      <para>
		In case <filename>FailsafeXServer</filename> is setup, that will be tried first.
		and this only used as a backup if even that server keeps
		crashing.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Xnest</term>
	    <listitem>
	      <synopsis>Xnest=/usr/bin/X11/Xnest</synopsis>
	      <para>
		The full path and arguments to the Xnest command.  This is used
		for the flexible Xnest servers.  This way the user can start new
		login screens in a nested window.  Of course you must have the Xnest
		server from your X server packages installed for this to work.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
      </sect3>

      <sect3 id="securitysection">
	<title>Security Options</title>
	
	<variablelist>
	  <title>[security]</title>
	  
	  <varlistentry>
	    <term>AllowRoot</term>
	    <listitem>
	      <synopsis>AllowRoot=true</synopsis>
	      <para>
		Allow root (privileged user) to log in through GDM.  Set
		this to false if you want to disallow such logins.
	      </para>
	      <para>
		On systems that support PAM, this parameter is
		not as useful as you can use PAM to do the same thing,
		and in fact do even more.  However it is still followed,
		so you should probably leave it true for PAM systems.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>AllowRemoteRoot</term>
	    <listitem>
	      <synopsis>AllowRemoteRoot=true</synopsis>
	      <para>
		Allow root (privileged user) to log in remotely through GDM.
		Set this to false if you want to disallow such logins.  Remote
		logins are any logins that come in through the xdmcp.
	      </para>
	      <para>
		On systems that support PAM, this parameter is
		not as useful as you can use PAM to do the same thing,
		and in fact do even more.  However it is still followed,
		so you should probably leave it true for PAM systems.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>AllowRemoteAutoLogin</term>
	    <listitem>
	      <synopsis>AllowRemoteAutoLogin=false</synopsis>
	      <para>
		Allow the timed login to work remotely.  That is, remote
		connections through XDMCP will be allowed to log into the
		"TimedLogin" user by letting the login window time out, just
		like the local user on the first console.
	      </para>
	      <para>
		Note that this can make a system quite insecure, and thus is
		off by default.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>DisallowTCP</term>
	    <listitem>
	      <synopsis>DisallowTCP=true</synopsis>
	      <para>
		If true, then always append <filename>-nolisten tcp</filename>
		to the command line
		of local X servers, thus disallowing TCP connection.  This is
		useful if you do not care for allowing remote connections, since
		the X protocol could really be potentially a security hazard to
		leave open, even though no known security problems exist.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RelaxPermissions</term>
	    <listitem>
	      <synopsis>RelaxPermissions=0</synopsis>
	      <para>
		By default GDM ignores files and directories writable to
		other users than the owner. 
	      </para> 
	      
	      <para> 
		Changing the value of RelaxPermissions makes it
		possible to alter this behavior:
	      </para>
	      
	      <para>
        	0 - Paranoia option. Only accepts user owned files and directories.
	      </para>
	      <para>
        	1 - Allow group writable files and directories.
	      </para>
	      <para>
        	2 - Allow world writable files and directories.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RetryDelay</term>
	    <listitem>
	      <synopsis>RetryDelay=3</synopsis>
	      <para>
		The number of seconds GDM should wait before
		reactivating the entry field after a failed login.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>UserMaxFile</term>
	    <listitem>
	      <synopsis>UserMaxFile=65536</synopsis>
	      <para>
		GDM will refuse to read/write files bigger than this number
		(specified in bytes).
	      </para>
	      
	      <para>
        	In addition to the size check GDM is extremely picky
        	about accessing files in user directories.  It will not
        	follow symlinks and can optionally refuse to
        	read files and directories writable by other than the
        	owner. See the <filename>RelaxPermissions</filename>
		option for more info.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
      </sect3>

      <sect3 id="xdmcpsection">
	<title>XDCMP Support</title>

	<variablelist>
	  <title>[xdmcp]</title>
	  
	  <varlistentry>
	    <term>DisplaysPerHost</term>
	    <listitem>
	      <synopsis>DisplaysPerHost=1</synopsis>
	      <para>
		To prevent attackers from filling up the pending
		queue, GDM will only allow one connection for each
		remote machine.  If you want to provide display
		services to machines with more than one screen, you
		should increase the <filename>DisplaysPerHost</filename>
		value accordingly.
	      </para>

	      <para>
		Note that the number of connections from the local
		machine is unlimited.  Only remote connections
		are limited by this number.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Enable</term>
	    <listitem>
	      <synopsis>Enable=false</synopsis>
	      <para>
		Setting this to true enables XDMCP support allowing remote displays/X
		terminals to be managed by GDM.
	      </para>
	      
	      <para>
		<filename>gdm</filename> listens for requests on UDP
		port 177. See the Port option for more information.
	      </para>
	      
	      <para>
		If GDM is compiled to support it, access from remote displays
		can be controlled using the TCP Wrappers library. The service name is 
		<filename>gdm</filename>
	      </para>
	      
	      <para>
		You should add 
	        <screen>
  gdm:	.my.domain
</screen>
		to your <filename>/etc/hosts.allow</filename>, depending on your
		TCP Wrappers configuration.  See the
		<ulink type="help" url="man:hosts.allow">hosts.allow(5)</ulink> man page for details.
	      </para>
	      
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>HonorIndirect</term>
	    <listitem>
	      <synopsis>HonorIndirect=true</synopsis>
	      <para>
		Enables XDMCP INDIRECT choosing (i.e. remote execution
		of <filename>gdmchooser</filename>) for X-terminals
		which don't supply their own display browser.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>MaxPending</term>
	    <listitem>
	      <synopsis>MaxPending=4</synopsis>
	      <para>
		To avoid denial of service attacks, GDM has fixed size
		queue of pending connections. Only MaxPending displays
		can start at the same time.
	      </para>
	      
	      <para>
		Please note that this parameter does *not* limit the
		number of remote displays which can be managed. It only
		limits the number of displays initiating a connection
		simultaneously.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>MaxPendingIndirect</term>
	    <listitem>
	      <synopsis>MaxPendingIndirect=4</synopsis>
	      <para>
		GDM will only provide <filename>MaxPendingIndirect</filename>
		displays with host choosers simultaneously.  If more queries
		from different hosts come in, the oldest ones will be forgotten.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>MaxSessions</term>
	    <listitem>
	      <synopsis>MaxSessions=16</synopsis>
	      <para>
		Determines the maximum number of remote display
		connections which will be managed
		simultaneously. I.e. the total number of remote displays
		that can use your host.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>MaxWait</term>
	    <listitem>
	      <synopsis>MaxWait=30</synopsis>
	      <para>
		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 XDMCP conversations.
	      </para>
	      
	      <para>
		GDM will then place the session id in the pending queue
		waiting for the display to respond with a MANAGE request.
	      </para>
	      
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>MaxWaitIndirect</term>
	    <listitem>
	      <synopsis>MaxWaitIndirect=30</synopsis>
	      <para>
		The MaxWaitIndirect parameter determines the maximum
		number of seconds between the time where a user chooses
		a host and the subsequent indirect query where the user is
		connected to the host.  When the timeout is exceeded, the
		information about the chosen host is forgotten and the indirect
		slot freed up for other displays.  The information may be
		forgotten earlier if there are more hosts trying to
		send indirect queries then <filename>MaxPendingIndirect</filename>.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>Port</term>
	    <listitem>
	      <synopsis>Port=177</synopsis>
	      <para>
		The UDP port number <filename>gdm</filename> should
		listen to for XDMCP requests. Don't change this unless
		you know what you're doing.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>PingIntervalSeconds</term>
	    <listitem>
	      <synopsis>PingIntervalSeconds=15</synopsis>
	      <para>
		Interval in which to ping the X server in seconds.  If the
		X server doesn't return before the next time we ping it,
		the connection is stopped and the session ended.  This is
		a combination of the XDM PingInterval and PingTimeout,
		but in seconds.
	      </para>

	      <para>
		Note that GDM in the past used to have a <filename>PingInterval</filename>
		configuration key which was also in minutes.  For most purposes
		you'd want this setting to be lower then one minute however since
		in most cases where XDMCP would be used (such as terminal labs),
		a lag of more then 15 or so seconds would really mean that the
		terminal was turned off or rebooted and you would want to end
		the session.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Willing</term>
	    <listitem>
	      <synopsis>Willing=etc/gdm/Xwilling</synopsis>
	      <para>
		When the server sends a WILLING packet back after a QUERY
		it sends a string that gives the current status of this
		server.  The default message is the system ID, but it is
		possible to create a script that displays customized
		message.  If this script doesn't exist or this key is
		empty the default message is sent.  If this script succeeds
		and produces some output, the first line of it's output
		is sent (and only the first line).  It runs at most once
		every 3 seconds to prevent possible denial of service
		by flooding the server with QUERY packets.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
      </sect3>

      <sect3 id="commonguioptions">
	<title>Common GUI Configuration Options</title>

	<variablelist>
	  <title>[gui]</title>
	  
	  <varlistentry>
	    <term>Gtkrc</term>
	    <listitem>
	      <synopsis>Gtkrc=</synopsis>
	      <para>
		Path to a <filename>gtkrc</filename> containing the
		theme for use in <filename>gdmlogin</filename> /
		<filename>gdmchooser</filename>.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>MaxIconWidth</term>
	    <listitem>
	      <synopsis>MaxIconWidth=128</synopsis>
	      <para>
		Specifies the maximum icon width (in pixels) that the
		face browser will display. Icons larger than this will
		be scaled.  This also affects icons in the XDMCP chooser.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>MaxIconHeight</term>
	    <listitem>
	      <synopsis>MaxIconHeight=128</synopsis>
	      <para>
		Specifies the maximum icon height (in pixels) that the
		face browser will display. Icons larger than this will
		be scaled.  This also affects icons in the XDMCP chooser.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
      </sect3>
	
      <sect3 id="greetersection">

	<title>Greeter Configuration</title>

	<variablelist>
	  <title>[greeter]</title>

	  <varlistentry>
	    <term>BackgroundColor</term>
	    <listitem>
	      <synopsis>BackgroundColor=#007777</synopsis>
	      <para>
		If the BackgroundType is 2, use this color in the background
		of the greeter.  Also use it as the back of transparent images
		set on the background and if the BackgroundRemoteOnlyColor
		is set and this is a remote display.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>BackgroundImage</term>
	    <listitem>
	      <synopsis>BackgroundImage=somefile.png</synopsis>
	      <para>
		If the BackgroundType is 1, then display this file as the
		background in the greeter.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>BackgroundProgram</term>
	    <listitem>
	      <synopsis>BackgroundProgram=/usr/bin/xeyes</synopsis>
	      <para>
		If set this program will be run in the background while
                the login window is being displayed.  Note that not all
		programs will run this way, since gdm does not usually have
		a home directory.  You could set up home directory for the
		gdm user if you wish to run applications which require it.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>BackgroundRemoteOnlyColor</term>
	    <listitem>
	      <synopsis>BackgroundRemoteOnlyColor=true</synopsis>
	      <para>
		On remote displays only set the color background.  This is
		to make network load lighter.  The <filename>BackgroundProgram</filename> is also
		not run.  This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>BackgroundScaleToFit</term>
	    <listitem>
	      <synopsis>BackgroundScaleToFit=true</synopsis>
	      <para>
		Scale background image to fit the screen.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>BackgroundType</term>
	    <listitem>
	      <synopsis>BackgroundType=2</synopsis>
	      <para>
		The type of background to set.  0 is none, 1 is image and 2
		is color.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>Browser</term>
	    <listitem>
	      <synopsis>Browser=true</synopsis>
	      <para>
		Set to true to enable the face browser. See the ``The Standard Greeter''
		section for more information on the face browser.  This option only
		works for the Standard Greeter.  For the Graphical Greeter,
		the face browser is enabled by choosing a theme which includes a
		face browser
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>ChooserButton</term>
	    <listitem>
	      <synopsis>ChooserButton=true</synopsis>
	      <para>
		If true, add a chooser button to the Actions menu that will
		restart the current server with a chooser.  XDMCP does not need
		to be enabled on the local machine for this to work.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>ConfigAvailable</term>
	    <listitem>
	      <synopsis>ConfigAvailable=true</synopsis>
	      <para>
		Allow the configurator to be run from the greeter.  Note that
		the user will need to type in the root password before the
		configurator is run however.  See the <filename>Configurator</filename> option
		in the daemon section.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>DefaultFace</term>
	    <listitem>
	      <synopsis>DefaultFace=share/pixmaps/nophoto.png</synopsis>
	      <para>
		Default icon file for users without a personal picture
		in <filename>~/gnome/photo</filename>. The image must be
		in an gdk-pixbuf supported format and the file must be
		readable for the gdm user.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>Exclude</term>
	    <listitem>
	      <synopsis>Exclude=bin,daemon,adm,lp,sync,shutdown,halt,mail,...</synopsis>
	      <para>
		Comma-separated list of usernames to exclude from the
		face browser. The excluded users will still be able to
		log in.  See also <filename>MinimalUID</filename>.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>GlobalFaceDir</term>
	    <listitem>
	      <synopsis>GlobalFaceDir=share/faces/</synopsis>
	      <para>
		Systemwide directory for face files. The sysadmin can
		place icons for users here without touching their
		homedirs. Faces are named after their users' logins.
	      </para>
	      
	      <para>
		I.e. <filename>&lt;GlobalFaceDir&gt;/johndoe</filename>
		would contain the face icon for the user ``johndoe''. No
		image format extension should be specified. 
	      </para>
	      
	      <para>
		The face images must be stored in gdk-pixbuf supported formats and
		they must be readable for the GDM user.
	      </para>
	      
	      <para>
		A user's own icon file will always take precedence over the sysadmin
		provided one.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>GraphicalTheme</term>
	    <listitem>
	      <synopsis>GraphicalTheme=circles</synopsis>
	      <para>
		The graphical theme that the Graphical Greeter should use.
		it should refer to a directory in the theme directory
		set by <filename>GraphicalThemeDir</filename>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>GraphicalThemeDir</term>
	    <listitem>
	      <synopsis>GraphicalThemeDir=share/gdm/themes/</synopsis>
	      <para>
		The directory where themes for the Graphical Greeter are
		installed.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>LocaleFile</term>
	    <listitem>
	      <synopsis>LocaleFile=etc/gdm/locale.alias</synopsis>
	      <para>
		File in format similar to the GNU locale format with entries
		for all supported languages on the system.  The format is
		described above or in a comment inside that file.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>LockPosition</term>
	    <listitem>
	      <synopsis>LockPosition=true</synopsis>
	      <para>
		If true the position of the login window of the Standard Greeter
		cannot be changed even if the title bar is turned on.
	      </para>
	    </listitem>
	  </varlistentry>	
	  
	  <varlistentry>
	    <term>Logo</term>
	    <listitem>
	      <synopsis>Logo=share/pixmaps/gnome-logo-large.png</synopsis>
	      <para>
		Image file to display in the logo box. The file must be
		in an gdk-pixbuf supported format and it must be readable by
		the GDM user. If no file is specified the logo feature
		is disabled.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>MinimalUID</term>
	    <listitem>
	      <synopsis>MinimalUID=100</synopsis>
	      <para>
		The minimal UID that gdm should consider a user.  All
		users with a lower UID will be excluded from the face browser.
		See also <filename>Exclude</filename>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>PositionX</term>
	    <listitem>
	      <synopsis>PositionX=200</synopsis>
	      <para>
		The horizontal position of the login window of the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>PositionY</term>
	    <listitem>
	      <synopsis>PositionY=100</synopsis>
	      <para>
		The vertical position of the login window of the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	
	  
	  <varlistentry>
	    <term>Quiver</term>
	    <listitem>
	      <synopsis>Quiver=true</synopsis>
	      <para>
		Controls whether <filename>gdmlogin</filename> should
		shake the display when an incorrect username/password is
		entered.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RemoteWelcome</term>
	    <listitem>
	      <synopsis>RemoteWelcome=Welcome to &percnt;n</synopsis>
	      <para>
		Controls which text to display next to the logo image in the
		greeter for remote XDMCP sessions.  The same expansion is
		done here as in the <filename>Welcome</filename> string.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RunBackgroundProgramAlways</term>
	    <listitem>
	      <synopsis>RunBackgroundProgramAlways=false</synopsis>
	      <para>
		If this is true then the background program is run always, otherwise
		it is only run when the <filename>BackgroundType</filename> is 0 (None)
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>SetPosition</term>
	    <listitem>
	      <synopsis>SetPosition=true</synopsis>
	      <para>
		If true the position of the login window of the Standard Greeter
		is determined by <filename>PositionX</filename> 
		/ <filename>PositionY</filename>.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>ShowGnomeFailsafeSession</term>
	    <listitem>
	      <synopsis>ShowGnomeFailsafeSession=true</synopsis>
	      <para>
		Should the greeter show the Gnome Failsafe session
		in the sessions list.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>ShowLastSession</term>
	    <listitem>
	      <synopsis>ShowLastSession=true</synopsis>
	      <para>
		Should the greeter show the 'Last' session in the
		session list.  If this is off, then GDM is in the
		so called 'switchdesk' mode which for example
		Red Hat uses.  That is, the users can't pick
		the last session and will just then get the default
		session (see <filename>DefaultSession</filename>)
		unless then pick something else for this session
		only.  So if this is off, this really circumvents
		saving of the last session.
	      </para>
	    </listitem>
	  </varlistentry>	

	  <varlistentry>
	    <term>ShowXtermFailsafeSession</term>
	    <listitem>
	      <synopsis>ShowXtermFailsafeSession=true</synopsis>
	      <para>
		Should the greeter show the Xterm Failsafe session
		in the sessions list.
	      </para>
	    </listitem>
	  </varlistentry>	
	  
	  <varlistentry>
	    <term>SystemMenu</term>
	    <listitem>
	      <synopsis>SystemMenu=true</synopsis>
	      <para>
		Turns the Actions menu (which used to be called System menu) on
		or off.  If this is off then one of the
		actions will be available anywhere.  These actions include
		Shutdown, Reboot, Configure, XDMCP chooser and such.  All of
		those can however be turned off individually.  Shutdown, Reboot
		and Suspend can be turned off by just setting the corresponding
		keys to empty.  Note that the
		actions menu is only shown on local logins as it would not be
		safe or even desirable on remote logins, so you don't have to
		worry about remote users having any sort of console privilages.
	      </para>

	      <para>
		Note that if this is off none of the actions will be available
		even if a theme for a graphical greeter mistakenly shows them.
		Also note that sometimes a graphical theme may not show all
		the available actions as buttons and you may have to press
		F10 to see the menu.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>TitleBar</term>
	    <listitem>
	      <synopsis>TitleBar=true</synopsis>
	      <para>
		Display the title bar in the greeter.
		This only affects the Standard Greeter.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Use24Clock</term>
	    <listitem>
	      <synopsis>Use24Clock=false</synopsis>
	      <para>
		Force the use of 24 hour clock even if the locale would default
		to a 12 hour clock.  In some locales that normally use 24 hour
		format (like czech, that is <filename>cs_CZ</filename>) this
		setting has no effect.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>UseCirclesInEntry</term>
	    <listitem>
	      <synopsis>UseCirclesInEntry=false</synopsis>
	      <para>
		Use circles instead of asterisks in the password entry.
		This may not work with all fonts however.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>Welcome</term>
	    <listitem>
	      <synopsis>Welcome=Welcome</synopsis>
	      <para>
		Controls which text to display next to the logo image in the
		standard greeter. The following control chars are supported:
	      </para>
	      
	      <para>
		&percnt;&percnt; &mdash; the `&percnt;' character
	      </para>
	      
	      <para>
		&percnt;d &mdash; display's hostname
	      </para>
	      
	      <para>
		&percnt;h &mdash; Fully qualified hostname
	      </para>

	      <para>
		&percnt;m &mdash; machine (processor type)
	      </para>

	      <para>
		&percnt;n &mdash; Nodename (i.e. hostname without .domain)
	      </para>
	      
	      <para>
		&percnt;r &mdash; release (OS version)
	      </para>
	      
	      <para>
		&percnt;s &mdash; sysname (i.e. OS)
	      </para>

	      <para>
		This string is only used for local logins.  For remote XDMCP
		logins we use <filename>RemoteWelcome</filename>.
	      </para>

	      <para>
		In the Graphical Greeter the location of this text depends on
		the theme.  Unless the theme uses the stock welcome string
		somewhere this string will not be displayed at all.
	      </para>
	      	      
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>XineramaScreen</term>
	    <listitem>
	      <synopsis>XineramaScreen=0</synopsis>
	      <para>
		If the Xinerama extension is active the login window
                will be centered on this physical screen (use 0 for
                the first screen, 1 for the second..).
	      </para>
	    </listitem>
	  </varlistentry>	

	</variablelist>

      </sect3>

      <sect3 id="choosersection">

	<title>XDCMP Chooser Options</title>

	<variablelist>
	  <title>[chooser]</title>

	  <varlistentry>
	    <term>AllowAdd</term>
	    <listitem>
	      <synopsis>AllowAdd=true</synopsis>
	      <para>
		If true, allow the user to add arbitrary hosts to the
		chooser.  This way the user could connect to any host
		that responds to XDMCP queries from the chooser.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Broadcast</term>
	    <listitem>
	      <synopsis>Broadcast=true</synopsis>
	      <para>
		If true, the chooser will broadcast a query to the local
		network and collect responses.  This way the chooser will
		always show all available managers on the network.  If you
		need to add some hosts not local to this network, or if you
		don't want to use a broadcast, you can list them explicitly
		in the <filename>Hosts</filename> key.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>DefaultHostImage</term>
	    <listitem>
	      <synopsis>DefaultHostImage=share/pixmaps/nohost.png</synopsis>
	      <para>
		File name for the default host icon. This image will be
		displayed if no icon is specified for a given host. The
		file must be in an gdk-pixbuf supported format and it must be
		readable for the GDM user.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>HostImageDir</term>
	    <listitem>
	      <synopsis>HostImageDir=share/hosts</synopsis>
	      <para>
		Repository for host icon files. The sysadmin can place
		icons for remote hosts here and they will appear in
		<filename>gdmchooser</filename>.
	      </para>
	      
	      <para>
		The file name must match the fully qualified name (FQDN) for
		the host.  The icons must be stored in gdk-pixbuf supported formats
		and they must be readable to the gdm user.
	      </para>
	      
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>Hosts</term>
	    <listitem>
	      <synopsis>Hosts=host1,host2</synopsis>
	      <para>
		The hosts which should be listed in the chooser.  The chooser
		will only list them if they respond.  This is done in addition
		to broadcast (if <filename>Broadcast</filename> is set), so you need not list
		hosts on the local network.  This is useful if your
		networking setup doesn't allow all hosts to be reachable
		by a broadcast packet.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>ScanTime</term>
	    <listitem>
	      <synopsis>ScanTime=4</synopsis>
	      <para>
		Specifies how many seconds the chooser should wait for
		replies to its BROADCAST_QUERY.  Really this is only the time
		in which we expect a reply.  We will still add hosts to the list
		even if they reply after this time.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
      </sect3>

      <sect3 id="serverdefs">

	<title>X Server definitions</title>

	<para>
	  To set up X servers, you need to provide gdm with
	  information about the installed X servers.  You can
	  have as many different definitions as you wish, each
	  identified with a unique name.  The name
	  <filename>Standard</filename>
	  is required.  If you do not specify this server, gdm
	  will assume default values for a 'Standard' server
	  and the path given by <filename>daemon/StandardXServer</filename>.
	  <filename>Standard</filename> is used as the default,
	  in situations when no other server has been defined.
	</para>

	<para>
	  Servers are defined by sections named <filename>server-</filename>
	  followed by the identifier of this server.  This should be a 
	  simple ASCII string with no spaces.  If you use the GUI
	  configurator, it will use random words for these.  These will
	  not be user visible, they are just needed to uniquely identify the
	  server.
	</para>
	
	<variablelist>
	  <title>[server-Standard]</title>

	  <varlistentry>
	    <term>name</term>
	    <listitem>
	      <synopsis>name=Standard server</synopsis>
	      <para>
		The name that will be displayed to the user.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>command</term>
	    <listitem>
	      <synopsis>command=/usr/bin/X11/X</synopsis>
	      <para>
		The command to execute, with full path to the binary
		of the X server, and any extra arguments needed.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>flexible</term>
	    <listitem>
	      <synopsis>flexible=true</synopsis>
	      <para>
		Indicates if this server is available as a choice when a
		user wishes to run a flexible, on demand server.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>handled</term>
	    <listitem>
	      <synopsis>handled=true</synopsis>
	      <para>
		Indicates that GDM should run the login window on this server
		and allow a user to log in.  If set to false, then GDM will just
		run this server and wait for it to terminate.  This can be useful
		to run an X terminal using GDM.  When this is done you should
		normally also add <filename>-terminate</filename> to the command
		line of the server to make the server terminate after each session.
		otherwise the control of the slave will never come back to GDM
		and for example soft restarts won't work, since GDM assumes there
		is a login in progress for the entire time this server is
		active.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>chooser</term>
	    <listitem>
	      <synopsis>chooser=false</synopsis>
	      <para>
		Indicates that GDM should instead of a login window run a chooser on
		this window and allow the user to choose which server to log into.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	</variablelist>

      </sect3>

      <sect3 id="localservers">

	<title>Local Static X Server Configuration</title>

	<para>
	  The static X servers are servers that are always running, when the server
	  ever dies, it is restarted.  You can have as many local static servers as
	  you wish.  Each key in the <filename>[servers]</filename> section corresponds
	  to the display number of the server to run.  For example normally there
	  is only one key, which is the key <filename>0</filename>, which corresponds
	  to the display <filename>:0</filename>.
	</para>

	<variablelist>
	  <title>[servers]</title>
	  
	  <varlistentry>
	    <term>&lt;display number&gt;</term>
	    <listitem>
	      <synopsis>0=Standard</synopsis>
	      <para>
		Control section for local X servers. Each line indicates
		the local display number and the command that needs to
		be run to start the X server(s).
	      </para>

	      <para>
		The command can either be a path to an X executable, or
		a name of one of the server definitions.  This can be
		followed by some arguments that should be passed to the
		X server when executed.
	      </para>

	      <para>
		The gdm daemon doesn't enforce the numbers to be in
		order or for them to be "packed".  However when you use
		the GUI configurator, the servers will always start from
		0 and go up by 1.  That is, leaving no holes.
	      </para>
	      
	      <para>
		GDM will splice "<filename>-auth
		  &lt;ServAuthDir&gt;/:n.Xauth :n</filename>", where n is
		the display number.  Inside the command line before all
		other arguments before running the server.
	      </para>

	      <para>
		On some systems it is necessary for gdm to know on which
		virtual consoles to run the X server.  In this case,
		(if running XFree86) add "vt7" to the command line for example
		to run on virtual console 7.  However on Linux this is normally
		done automatically if <filename>VTAllocation</filename> key
		is set.
	      </para>

	      <para>
		Normally you do not need to add a <filename>-nolisten tcp</filename>
		flag as this is added automatically for local servers when
		the <filename>DisallowTCP</filename> option is set.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	</variablelist>

      </sect3>
	
    </sect2>

    <sect2 id="userconfig">
      <title>Per User Configuration</title>

      <para>
	There are some per user configuration settings that control how GDM behaves.
	Firstly there is the <filename>~/.dmrc</filename> file.  In theory this
	file should be shared between GDM and KDM, so users only have to configure
	things once.  This is a standard <filename>.ini</filename> style configuration
	file.  It has one section called <filename>[Desktop]</filename> and can have
	two keys, <filename>Session</filename>, which is the basename of the session
	<filename>.desktop</filename> file that the user wishes to normally use
	and a <filename>Language</filename> key that is the language that the user
	wishes to use.  If either of these keys is missing, the system default is
	used.  The file would normally look as follows:
      </para>

      <screen>
	[Desktop]
	Session=gnome.desktop
	Language=cs_CZ.UTF-8
</screen>

      <para>
	The user can also configure a face image for the face browser.  This is
	done by copying an image into a file called <filename>~/.face</filename>.
	This should be a standard image that GTK+ can read, such as PNG.
      </para>

      <para>
	Face images can also be placed in the global face directory, which is
	normally <filename>share/faces/</filename>
        (though this can be configured with the <filename>GlobalFaceDir</filename>
        configuration option) and the filename should be the name of
        the user, optionally with a <filename>.png</filename> appended.
      </para>
    </sect2>
    
  </sect1>

  <sect1 id="controlling">
    <title>Controlling GDM</title>

    <para>
      You can control GDM behavior during runtime in several different ways.  You can
      either run certain commands, or you can talk to GDM using either a unix socket
      protocol, or a FIFO protocol.
    </para>

    <sect2 id="commands">
      <title>Commands</title>

      <para>
	To stop GDM, you can either send the TERM signal to the main daemon or run
	the <filename>gdm-stop</filename> command which is in the <filename>sbin/</filename>
	directory.  To restart GDM, you can either send the HUP signal to the main daemon or run
	the <filename>gdm-restart</filename> command which is also in the <filename>sbin/</filename>
	directory.
	To restart GDM but only after all the users have logged out, you can either send
	the USR1 signal to the main daemon or run
	the <filename>gdm-safe-restart</filename> command which is in the <filename>sbin/</filename>
	directory as well.
      </para>

      <para>
	The <filename>gdmflexiserver</filename> command can be used to start new flexible (on demand)
	servers.  Run <filename>gdmflexiserver --help</filename> to get a listing of possible
	options.  This command will also lock the current screen with xscreensaver so that
	the user can safely walk away from the machine and let someone else log in.  XFree86 will
	automatically switch back to the same virtual terminal (if your operating system supports it),
	after the new session has ended, so this should work quite transparently to the users.
      </para>
      
    </sect2>

    <sect2 id="socketprot">
      <title>Socket Protocol</title>

      <para>
	GDM provides a unix domain socket for communication at <filename>/tmp/.gdm_socket</filename>.
	Using this you can check if GDM is running, the version of the daemon, the current
	servers that are running and who is logged in on them, and if GDM supports it on your
	operating system, also the virtual terminals of all the console logins.  You can also request
	new flexible servers to be run with this protocol, but this is best done with the
	<filename>gdmflexiserver</filename> command.
      </para>

      <para>
	Full and up to date documentation of the commands and their use is contained in the 
	GDM source tree in the file <filename>daemon/gdm.h</filename>.  Look for the
	defines starting with <filename>GDM_SUP_</filename>.
      </para>

    </sect2>

    <sect2 id="fifoprot">
      <title>The FIFO protocol</title>

      <para>
	GDM also provides a FIFO called <filename>.gdmfifo</filename> in the
	<filename>ServAuthDir</filename> directory
	(usually <filename>var/gdm/.gdmfifo</filename>).  You must be root to use this protocol,
	and it is mostly used for internal GDM chatter.  It is a very simple protocol where
	you just echo a command on a single line to this file.  It can be used to tell
	GDM things such as restart, suspend the machine, or restart all X servers next
	time it has a chance (which would be useful from an X configuration program).
      </para>

      <para>
	Full and up to date documentation of the commands and their use is contained in the 
	GDM source tree in the file <filename>daemon/gdm.h</filename>.  Look for the
	defines starting with <filename>GDM_SOP_</filename>.  The commands which require the
	pid of the slave as an argument are the ones that are really used for internal
	communication of the slave with the master and should not be used.
      </para>

    </sect2>
  </sect1>

  <sect1 id="binaries">
    <title>GDM and Related Commands</title>

    <para>
      The GDM package provides quite a few different commands.
    </para>

    <sect2 id="gdmcommandline">
      <title>GDM Command Line Options</title>

      <para>
        First command is the <filename>gdm</filename> command which is really just a script
        which runs the <filename>gdm-binary</filename>.  If you really need to set
        some environment before launching GDM, you can do it in this file.  This command
	accepts several command line parameters.
      </para>

      <variablelist>
	<title><filename>gdm</filename> Command Line Options</title>

	<varlistentry>
	  <term>--help</term>
	  <listitem>
	    <para>
              Gives a brief overview of the command line options.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>-nodaemon</term>
	  <listitem>
	    <para>
              If this option is specified, then gdm does not fork into the background when
              run.  You can use just a single dash with this option to preserve compatibility
              with XDM.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>--no-console</term>
	  <listitem>
	    <para>
              Tell the daemon that it should not run anything on the console.  This means that
              none of the local servers from the <filename>[servers]</filename> section will
              be run, and the console will not be used for communicating errors to the user.
              An empty <filename>[servers]</filename> section automatically implies this
              option.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>--preserve-ld-vars</term>
	  <listitem>
	    <para>
              When clearing the environment internally, preserve all variables starting with
              LD_.  This is mostly for debugging purposes.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>

    </sect2>

    <sect2 id="mainbinaries">
      <title>Other Main GDM Commands</title>

      <para>
        Next are the two greeters, <filename>gdmlogin</filename> which is the
        Standard Greeter, and <filename>gdmgreeter</filename> which is the
        Graphical Greeter.  There is also the <filename>gdmchooser</filename>
	which is the XDMCP chooser application.  These should all be run
	only from GDM and not by itself, although <filename>gdmchooser</filename>
	could theoretically be run as a standalone application which prints
	the chosen host on the standard output.
      </para>

      <para>
	There is also the setup program which is the <filename>gdmsetup</filename>
	command.  Normally on systems that support the PAM userhelper, this
	is setup such that when you run <filename>gdmsetup</filename> as
	an ordinary user, it will first ask you for your root password.
      </para>

      <para>
	There is also the user picture setup program, <filename>gdmphotosetup</filename>.
	This is run by users to setup their face browser picture.
      </para>

      <para>
	There are also the commands <filename>gdm-stop</filename>, <filename>gdm-restart</filename>
	and <filename>gdm-safe-restart</filename> which stop, restart, or restart the
	GDM daemon after all users have logged out, respectively.  These are
	installed in the <filename>sbin/</filename> directory.
      </para>

      <para>
	Finally there is the <filename>gdmflexiserver</filename> command which runs
	flexible (on demand) X servers.
      </para>

    </sect2>

    <sect2 id="extrabins">
      <title>Extra GDM Commands</title>

      <para>
	There are some extra commands provided as well.  First is the <filename>gdmXnestchooser</filename>
	command.  This command can run Xnest with all the right options and automatically getting
	the correct display number and setting up access, and runs the server as an indirect query
	to the local host by default.  This way you get an XDMCP chooser provided by your machine.
	You can also supply as an argument the hostname whose chooser should be displayed, so
	<filename>gdmXnestchooser somehost</filename> will run the XDMCP chooser from host
	<filename>somehost</filename> inside an Xnest.  You can make this command do a direct query
	instead by passing the <filename>-d</filename> option as well.
      </para>

      <para>
	Also useful is the <filename>gdmXnest</filename> command which is just for more
	easily running Xnest on your machine.  It will print out the display setting on standard
	output that you can use to connect to this server.  This is useful mostly for developers
	who perhaps wish to test their apps running on a completely separate server.
      </para>

      <para>
	For Graphical Greeter theme developers, there is the <filename>gdmthemetester</filename>
	command which can run the Graphical Greeter in a simulated debug environment for any
	selected theme.  Run the command with no options to get help.
      </para>

    </sect2>
  </sect1>

  <!-- ============= Theme manual ============================= -->

  <sect1 id="thememanual">
    <title>Graphical Greeter Themes</title>

    <para>
      This section describes the creation of themes for the Graphical
      Greeter.  For examples including screenshots, see the standard installed
      themes and the themes from
      <ulink type="http" url="http://art.gnome.org/themes/gdm_greeter/index.php">
      the theme website</ulink>.
    </para>

    <sect2 id="themeover">
      <title>Theme Overview</title>

      <para>
        GDM Themes can be created by creating an XML file that follows the
        specification in gui/greeter/greeter.dtd.  Theme files are stored
        in the directory <filename>share/gdm/themes/&lt;theme_name&gt;</filename>.
        Usually this would be under /usr/share.  The theme directory should contain a
        file called <filename>GdmGreeterTheme.desktop</filename> which has similar format to other
        .desktop files and looks like:
      </para>

      <screen>
     [GdmGreeterTheme]
     Encoding=UTF-8
     Greeter=circles.xml
     Name=Circles
     Description=Theme with blue circles
     Author=Bond, James Bond
     Copyright=(c) 2002 Bond, James Bond
     Screenshot=screenshot.png
</screen>

      <para>
        The Name, Description, Author and Copyright fields can be translated just
        like the other <filename>.desktop</filename>files.  All the files that are mentioned should
        be in the theme directory itself.  The Screenshot field points to a file
        which should be a 200x150 screenshot of the theme in action (it is OK
        not to have one, but it makes it nicer for user).  The Greeter field points
        to an XML file that contains the description of the theme.   The description
        will be given later.
      </para>

      <para>
        Once you have theme ready and installed you can test it with the installed
        <filename>gdmthemetester</filename> script.  This script assumes that you also have installed
        the Xnest X server.  It takes two arguments, first the environment that
        should be used.  This is one of console, console-timed, flexi, remote-flexi,
        xdmcp.  Where console is a standard console login, console-timed is a
        console login with a timed login going on, flexi is for any local
        flexible server, remote-flexi is for flexi server that is not local (such
        as an Xnest flexiserver run from a remote display) and xdmcp is for remote
        xdmcp connections.  The second argument is the theme name.  So for example
        to test how things look in the xdmcp mode with the circles theme you would
        run:
      <screen>gdmthemetester xdmcp circles</screen>
        Be sure to test all the environments with your theme, and make sure to test
        how the caps lock warning looks by pressing caps lock.  This is also a good
        way to take screenshots, just take a screenshot of the Xnest window.  This
        can be done in GNOME by focusing the Xnest window and pressing
        Alt-PrintScreen.
      </para>

      <para>
        Once you have all this done, then make a tarball that contains the directory
        name (so that you could just untar it in the <filename>/usr/share/gdm/themes</filename> directory).
        And this is the tarball you distribute and people can install from the
        graphical setup program.  You can do this with the commands:
      <screen>
     cd /usr/share/gdm/themes
     tar czvf &lt;theme_name&gt;.tar.gz &lt;theme_name&gt;/
</screen>
      </para>

    </sect2>

    <sect2 id="descofthemeformat">
      <title>Detailed Description of Theme XML format</title>

      <sect3 id="boxnodes">
        <title>Box Nodes</title>

        <para>
          Box nodes are container nodes for item nodes.  Box nodes are
          specified as follows:
      <screen>
     &lt;box orientation="alignment" min-width="num" xpadding="num"
      ypadding="num" spacing="num" homogeneous="bool"&gt;
</screen>
	  Where "num" means number and bool means either "true"
	  or "false".  The alignment value can be either "horizontal" or "vertical".
	  If you leave any property off it will default to
	  zero or "false" in case of "homogeneous", and "vertical" for
	  the orientation.
        </para>

	<para>
	  If the box is homogeneous then the children are allocated equal
	  amount of space.
	</para>
      </sect3>

      <sect3 id="itemnodes">
        <title>Item Nodes</title>

        <para>
          A GDM Theme is created by specifying a hierarchy of item and box
          nodes.  Item nodes can have the following value for "type":
        </para>

	<variablelist>
	  <varlistentry>
	    <term>entry</term>
	    <listitem>
	      <para>
		Text entry field.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>list</term>
	    <listitem>
	      <para>
		A list widget.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>label</term>
	    <listitem>
	      <para>
		A text label.  Must have a "text" node to specify the text.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>pixmap</term>
	    <listitem>
	      <para>
		An pixmap image in a format that gdk-pixbuf supports like
		PNG, JPEG, Tiff, etc...)
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>rect</term>
	    <listitem>
	      <para>
		Rectangle.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>svg</term>
	    <listitem>
	      <para>
		Scaled Vector Graphic image.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>

        <para>
          For example: 
        <screen>
       &lt;item type="label"&gt;
</screen>
          Items can specify ID values which gives them a specific look
          and feel or formatting.  Furthermore you can customize the login
          process by adding custom widgets with custom id's for some items
          (currently only the list item)
        </para>

        <para>
          Entry items can have id values as follows:
        </para>

	<variablelist>
	  <varlistentry>
	    <term>user-pw-entry</term>
	    <listitem>
	      <para>
                Entry field for userid and password entry.  This is
                the field used for responses for the PAM/GDM questions
                (Username, Password, etc..).
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>


        <para>
          List items can have id values as follows:
        </para>

	<variablelist>
	  <varlistentry>
	    <term>userlist</term>
	    <listitem>
	      <para>
                A user browser list, so that users can pick
                their username by clicking on this instead
                of typing.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>

        <para>
          Furthermore, you can have an arbitrary id (I'd recommend starting
          the id with 'custom' not to conflict with future additions to this
          spec) and ask extra information of the user.  See the section
          'Custom Widgetry'
        </para>

        <para>
          Label items can have id values as follows:
        </para>

	<variablelist>
	  <varlistentry>
	    <term>clock</term>
	    <listitem>
	      <para>
                Label the displays the date and time.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>pam-prompt</term>
	    <listitem>
	      <para>
	        Label the displays PAM prompt.  This is the prompt that
		PAM uses to ask for username, password, etc...
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>pam-error</term>
	    <listitem>
	      <para>
	        Label the displays PAM/GDM error messages.  Such as when
		user can't log in.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>pam-message</term>
	    <listitem>
	      <para>
	        Label the displays PAM message.  These are messages that
		PAM/GDM gives about state of the account, help about the
		prompts and other information.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>timed-label</term>
	    <listitem>
	      <para>
	        Label that displays timed login information.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
                     
        <para>
          Rectangles can have id values as follows:
        </para>

	<variablelist>
	  <varlistentry>
	    <term>caps-lock-warning</term>
	    <listitem>
	      <para>
	        Displays an icon that shows if the
		CAPS LOCK key is depressed.  This rectangle
		will be hidden/shown appropriately
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>

        <para>
          If an item is of type rect, the item can be a button.  Buttons
          must also include a "button" value as follows:
	<screen>
       &lt;item type="rect" id="disconnect_button" button="true"&gt;.
</screen>
        </para>

        <para>
          Possible values for button ids are as follows:
        </para>

	<variablelist>
	  <varlistentry>
	    <term>chooser_button</term>
	    <listitem>
	      <para>
	        Runs the XDMCP chooser.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>config_button</term>
	    <listitem>
	      <para>
	        Runs the GDM Setup program.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>disconnect_button</term>
	    <listitem>
	      <para>
	        Disconnect from remote session.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>language_button</term>
	    <listitem>
	      <para>
	        Displays the language selection dialog.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>halt_button</term>
	    <listitem>
	      <para>
		Halt (shuts down) the system.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>reboot_button</term>
	    <listitem>
	      <para>
		Reboot the system.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>session_button</term>
	    <listitem>
	      <para>
	        List and select from available sessions.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>suspend_button</term>
	    <listitem>
	      <para>
	        Suspend the system.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>system_button</term>
	    <listitem>
	      <para>
		Perform halt/reboot/suspend/etc. options
		(if allowed by gdm configuration).  Also
		allows user to run configurator if user
		enters root password (again if allowed
	        by gdm configuration).  This is usually
		now labeled Actions, and referred to as
		the Actions menu.
	      </para>
	    </listitem>
	  </varlistentry>

	</variablelist>
      </sect3>

      <sect3 id="positionnodes">
        <title>Position Node</title>

        <para>
          Each item can specify its position and size via the "pos" node.
          For example:
        <screen>
       &lt;pos x="0" y="4" width="100%" height="100%"/&gt;
</screen>
        </para>

	<para>
	  Both position and size can be given in percent and it will be taken
	  as the percentage of the size of the current container.  For toplevel
	  items it's the percentage of the whole screen.
	</para>

	<para>
	  For x and y, you can also specify a negative position which means position
	  from the right or bottom edge.  But this only applies with absolute
	  coordinates.  With percentage you can specify negative position and
	  it will be still from the same edge.
	</para>

	<para>
	  The position also specifies the anchor of the item, this can be
	  "n", "ne", "e", "se", "s", "sw", "w" and "nw" or "center" which stand
	  for the different edges/corners or "center" for center.  For example:
        <screen>
       &lt;pos x="10%" y="50%" anchor="w" width="80%" height="95"/&gt;
</screen>
	</para>

	<para>
	  If the item contains a box, you can specify width and height to be
	  "box" to mean that they are supposed to be the width and height
	  of the box, that is the items in the box plus the padding.
	</para>

	<para>
	  You can also specify an "expand" property to either be "true"
	  or false.  If true then the child will be expanded in the box
	  as much as possible (that is it will be given more space if available).
	</para>
      </sect3>

      <sect3 id="shownodes">
        <title>Show Node</title>

        <para>
          Some items may only display in certain modes, like when doing a
          remote display.  Multiple values can be specified and must be
          separated with commas.  The following values are possible:
	</para>

	<para>
          <filename>console</filename> - In console mode.
	</para>
	<para>
          <filename>console-fixed</filename> - In console non-flexi mode.
	</para>
	<para>
          <filename>console-flexi</filename> - In console &amp; flexi mode.
	</para>
	<para>
          <filename>flexi</filename> - In flexi mode.
	</para>
	<para>
          <filename>remote</filename> - In remote mode.
	</para>
	<para>
          <filename>remote-flexi</filename> - In remote &amp; flexi mode.
	</para>

	<para>
	  For example:
	<screen>
       &lt;show modes="flexi,remote"/&gt;
</screen>
	</para>

        <para>
          You can also specify the "type" value to indicate that certain
          items should only be displayed if the type is true.  Valid values
          include the following:
	</para>

	<para>
          <filename>chooser</filename>, if ChooserButton is set to "true" in <filename>gdm.conf</filename> file.
	</para>
	<para>
          <filename>config</filename>, if ConfigAvailable is set to "true" in <filename>gdm.conf</filename> file.
	</para>
	<para>
          <filename>halt</filename>, if HaltDaemon is specified in <filename>gdm.conf</filename> file.
	</para>
	<para>
          <filename>reboot</filename>, if RebootCommand is specified in <filename>gdm.conf</filename> file.
	</para>
	<para>
          <filename>suspend</filename>, if SuspendCommand is specified in <filename>gdm.conf</filename> file.
	</para>
	<para>
          <filename>system</filename>, if SystemMenu is specified in <filename>gdm.conf</filename> file
	</para>
	<para>
          <filename>timed</filename>, if TimedLoginEnabled is set to "true" in <filename>gdm.conf</filename> file.
	</para>

	<para>
          For example:
	<screen>
       &lt;show modes="console" type="system"/&gt;
</screen>
	</para>

	<para>
          Note that if SystemMenu is off then all of halt, reboot, suspend, chooser
          and config will not show, so this is a global toggle for them all.
          See some of the standard themes for how the show modes are used.
	</para>
      </sect3>

      <sect3 id="noractprenodes">
        <title>Normal/Active/Prelight Nodes</title>

        <para>
  	  Depending on the item type, it can specify its color, font, or
	  image via the following tags:
        </para>

        <para>
          <filename>normal</filename> - normal state.
        </para>
        <para>
          <filename>active</filename> - when the item has active focus.
        </para>
        <para>
          <filename>prelight</filename> - when the mouse is hovering over the item.
        </para>

        <para>
	  When item is "rect" (alpha can be omitted and defaults to 0.0):
	<screen>
       &lt;normal color="#ffffff" alpha="0.0"&gt;
</screen>
        </para>

        <para>
	  When item is "label":
	<screen>
       &lt;normal color="#ffffff" font="Sans 14"/&gt;
</screen>
        </para>

        <para>
	  When the item type is "pixmap" or "SVG", then the normal, active,
	  and prelight tags specify the images to use as follows:
	<screen>
       &lt;normal file="picture.png" tint="#dddddd"/&gt;
</screen>
        </para>

        <para>
	  Note that relative pathnames are assumed to be in the same 
	  directory as the theme .xml file in share/gdm/themes/&lt;theme_name&gt;.
        </para>
      </sect3>

      <sect3 id="textnodes">
        <title>Text Node</title>

        <para>
	  Text tags are used by labels.   They can be used to display
	  localized text as follows (if the "xml:lang" attribute is
	  omitted, the C locale is assumed):
	<screen>
       &lt;text xml:lang="fr"&gt;Option&lt;/text&gt;
</screen>
        </para>

	<para>
	  You can include pango markup in the text nodes for labels, however
	  you must encode it.  So for example to have the label of
	  "foo&lt;sup&gt;bar&lt;/sup&gt;", you must type:
	<screen>
       &lt;text"&gt;foo&amp;lt;sup&amp;gt;bar&amp;lt;/sup&amp;gt;&lt;/text&gt;
</screen>
	</para>

      </sect3>

      <sect3 id="stocklabels">
        <title>Stock</title>

        <para>
	  Certain common localized labels can be specified via the stock
	  tags.  The "text" tag is ignored if the "stock" tag is used.   You
	  should really use the stock labels rather then just putting all
	  the translations into the themes.  This gives faster load times
	  and likely better translations.  The following values are valid:
        </para>

	<para>
          <filename>caps-lock-warning</filename>, _("You've got capslock on!") 
        </para>
        <para>
          <filename>chooser</filename>, _("_XDMCP Chooser")
        </para>
        <para>
          <filename>disconnect</filename>, _("D_isconnect")
        </para>
        <para>
          <filename>halt</filename>, _("Shut_down")
        </para>
        <para>
          <filename>language</filename>, _("_Language")
        </para>
        <para>
          <filename>quit</filename>, _("_Quit")
        </para>
        <para>
          <filename>reboot</filename>, _("_Reboot")
        </para>
        <para>
          <filename>session</filename>, _("_Session")
        </para>
        <para>
          <filename>suspend</filename>, _("Sus_pend")
        </para>
        <para>
          <filename>system</filename>, _("_Actions")  (Formerly "S_ystem")
        </para>
        <para>
          <filename>timed-label</filename>, _("User %s will login in %d seconds")
        </para>
        <para>
          <filename>username-label</filename>, _("Username:")
        </para>
        <para>
          <filename>welcome-label</filename>, _("Welcome to %h")
        </para>

        <para>
	  For example:
	<screen>
       &lt;stock type="welcome-label"/&gt;
</screen>
        </para>

      </sect3>

      <sect3 id="customwidgetry">
        <title>Custom Widgetry</title>

        <para>
	  Currently there is one item which can be customizable and this is
	  the list item.  If you need to ask the user extra things, such as
	  to pick from a list of places to log into, or set of custom login
	  sessions you can setup the list item and add listitem children that
	  describe the choices.  Each listitem must have an id and a text child.
	  The choice will be recorded in the file
	  <filename>&lt;ServAuthDir&gt;/&lt;display&gt;.GreeterInfo</filename>
	  as <filename>&lt;list id&gt;=&lt;listitem id&gt;</filename>.
        </para>

        <para>
	  For example suppose we are on display :0, ServAuthDir is /var/gdm
	  and we have the following in the theme:
        </para>

	<screen>
    &lt;item type="list" id="custom-config"&gt;
      &lt;pos anchor="nw" x="1" y="1" height="200" width="100"/&gt;
      &lt;listitem id="foo"&gt;
        &lt;text&gt;Foo&lt;/text&gt;
      &lt;/listitem&gt;
      &lt;listitem id="bar"&gt;
        &lt;text&gt;Bar&lt;/text&gt;
      &lt;/listitem&gt;
    &lt;/item&gt;
</screen>

        <para>
	  Then if the user chooses 'Foo' then <filename>/var/gdm/:0.GreeterInfo</filename> will
	  contain:
        <screen>
       custom-config=foo
</screen>
        </para>

      </sect3>
    </sect2>
  </sect1>

  <sect1 id="exampleconf">
    <title>Example Configurations</title>

    <para>
      This section has some example configurations that are useful for
      various setups.
    </para>

    <sect2 id="terminallab">
      <title>Terminal Lab With One Server</title>

      <para>
	Suppose you want to make a lab full of X terminals that all connect
	to one main server.  So let's call one X terminal <filename>xterminal</filename>
	and lets call the server <filename>appserver</filename>.  You install
	GDM on both.
      </para>

      <para>
	On <filename>appserver</filename> you enable XDMCP, so you have
        <screen>
   [xdmcp]
   Enable=true
</screen>
	If you want no local screens here, you can then
	make the <filename>[servers]</filename> section empty.
      </para>

      <para>
	On the <filename>xterminal</filename> you disable XDMCP (you don't
	want anyone to connect to the xterminal really).  You will add a server type
	perhaps called <filename>Terminal</filename> as follows:
	<screen>
   [server-Terminal]
   name=Terminal server
   command=/usr/X11R6/bin/X -terminate
   flexible=false
   handled=false
</screen>
	This definition should in fact be included in the standard configuration
	file.  Notice that we made the <filename>handled</filename> key false
	since we don't want GDM to handle this server localy.  Also note that
	we have not yet added the <filename>-query</filename> argument, you can add
	that here, or in the <filename>[servers]</filename> section.  We'll define
	our local servers as follows:
	<screen>
   [servers]
   0=Terminal -query appserver
</screen>
	This will run a direct XDMCP query to the server named
	<filename>appserver</filename>.
      </para>
    </sect2>

    <sect2 id="terminallabtwo">
      <title>Terminal Lab With Two Or More Servers</title>

      <para>
	Suppose you want to make a lab full of X terminals that all connect
	to some choice of servers.  For now let's make it <filename>appserverone</filename>
	and <filename>appservertwo</filename>.  Again we'll call our example
	X terminal machine <filename>xterminal</filename>.  The setup on
	both servers is the same as with the case of one server in the previous
	section.  You do not need to explicitly enable indirect queries on the
	server since we'll run the choosers locally on the X terminals.
      </para>

      <para>
	So on the <filename>xterminal</filename> you again disable XDMCP.
	You will add a server type perhaps called <filename>Chooser</filename> as follows:
	<screen>
    [server-Chooser]
    name=Chooser server
    command=/usr/X11R6/bin/X
    flexible=false
    chooser=true
</screen>
	And again this definition should in fact be included in the standard configuration
	file.  Notice that we made the <filename>chooser</filename> key true here.
	This will run the XDMCP chooser for this server, and when the user chooses
	a host GDM will run a query for that host.  Then we'll define
	our local servers as follows:
	<screen>
   [servers]
   0=Chooser
</screen>
      </para>

      <para>
	The XDMCP chooser on the X terminal will normally give a broadcast query to
	see which servers exist on the network.  If the two servers are not reachable
	by a broadcast query, you must add them by hand to the configuration file.
	So in the <filename>[chooser]</filename> section you would have:
	<screen>
   Hosts=appserverone,appservertwo
</screen>
	and any other servers you wish the users to be able to connect to.
      </para>

      <para>
	Sometimes you may want to run the chooser on the server side however.  Then
	what you want to do is to run a configuration similar to the previous
	section about the one server configuration with XDMCP indirect queries
	enabled on <filename>appserver</filename> and on the X terminals you'd have
	<screen>
   [servers]
   0=Terminal -indirect appserver
</screen>
	This way for example you only have to maintain one <filename>Hosts</filename>
	entry.  However as a disadvantage then, the <filename>appserver</filename>
	must then always be available.  So it's not good for situations where
	you want to have serveral servers and not all of them have to be on
	all the time.  You could also have one of the X terminals handle
	indirect XDMCP queries and serve up the chooser to the other X terminals.
      </para>
    </sect2>
  </sect1>

  <!-- ============= Application License ============================= -->

  <sect1 id="license">
    <title>License</title>
    <para>
      This program is free software; you can redistribute it and/or
      modify it under the terms of the  <ulink type="help" url="gnome-help:gpl">
      <citetitle>GNU General Public License</citetitle></ulink> as
      published by the Free Software Foundation; 
      either version 2 of the License, or (at your option) any later
      version.
    </para>
    <para>
      This program is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      <citetitle>GNU General Public License</citetitle> for more details.
    </para>
    <para>
      A copy of the <citetitle>GNU General Public License</citetitle> is
      included as an appendix to the <citetitle>GNOME Users
      Guide</citetitle>.  You may also obtain a copy of the
      <citetitle>GNU General Public License</citetitle> from the Free
      Software Foundation by visiting <ulink type="http"
      url="http://www.fsf.org">their Web site</ulink> or by writing to
      <address>
      Free Software Foundation, Inc.
      <street>59 Temple Place</street> - Suite 330
      <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
      <country>USA</country>
      </address>
    </para>
  </sect1>
  
</article>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->