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.17.7"> 
    <!ENTITY date "02/12/2007"> 
]>

<article id="index" lang="en">
  <articleinfo>
    <title>Gnome Display Manager Reference Manual</title>

    <revhistory>
      <revision>
        <revnumber>0.0</revnumber>
        <date>2007-01</date>
      </revision>
    </revhistory>

    <abstract role="description">
      <para>
        GDM is the GNOME Display Manager, a graphical login program.
      </para>
    </abstract>

    <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 role="maintainer">
        <firstname>Brian</firstname><surname>Cameron</surname>
        <affiliation>
          <address><email>Brian.Cameron@Sun.COM</email></address>
        </affiliation>
      </author>
      <author>
        <firstname>Bill</firstname><surname>Haneman</surname>
        <affiliation>
          <address><email>Bill.Haneman@Sun.COM</email></address>
        </affiliation>
      </author>
    </authorgroup>
    <copyright>
      <year>1998</year><year>1999</year><holder>Martin K. Petersen</holder>
    </copyright>
    <copyright>
      <year>2001</year><year>2003</year><year>2004</year>
        <holder>George Lebl</holder>
    </copyright>
    <copyright>
      <year>2003</year> <holder>Red Hat, Inc.</holder>
    </copyright>
    <copyright>
      <year>2003</year><year>2004</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>
      Chooser - A program used to select a remote host for managing a
      display remotely on the local display (<command>gdmchooser</command>).
    </para>

    <para>
      Configurator - The configuration application
      (<command>gdmsetup</command>).
    </para>

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

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

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

    <para>
      GTK+ Greeter - The standard login window (<command>gdmlogin</command>).
    </para>

    <para>
      PAM - Pluggable Authentication Mechanism
    </para>

    <para>
      Themed Greeter - The themable login window (
      <command>gdmgreeter</command>).
    </para>

    <para>
      XDMCP - X Display Manage Protocol
    </para>

    <para>
      Paths that start with a word in angle brackets are relative to the
      installation prefix. I.e. <filename>&lt;share&gt;/pixmaps/</filename>
      refers to <filename>&lt;share&gt;/pixmaps</filename> if GDM was configured
      with <command>--prefix=/usr</command>.  Normally also note that
      GDM is installed with <command>--sysconfigdir=&lt;etc&gt;/X11</command>,
      meaning any path to which we refer to as
      <filename>&lt;etc&gt;/gdm/PreSession</filename> usually means
      <filename>&lt;etc/X11&gt;/gdm/PreSession</filename>.  Note that for
      interoperability it is recommended that you use a --prefix of
      <filename>/usr</filename> and a --sysconfdir of
      <filename>&lt;etc&gt;/X11</filename>.
    </para>
  </sect1>

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

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

      <para> 
        The Gnome Display Manager (GDM) is a display manager that
        implements all significant features required for managing
        local and remote displays.   GDM was written from scratch and
        does not contain any XDM / X Consortium code.
      </para>

      <para>
        For further information about GDM, see the
        <ulink type="http" url="http://www.gnome.org/projects/gdm/">
        the GDM project website</ulink>.  Please submit any bug reports or
        enhancement requests to the &quot;gdm&quot; category in
        <ulink type="http" url="http://bugzilla.gnome.org/">bugzilla.gnome.org</ulink>.
        You can also send a message to the 
        <address><email>gdm-list@gnome.org</email></address> mail list to
        discuss any issues or concerns with the GDM program.
      </para>
    </sect2>

    <sect2 id="stability">
      <title>
        Interface Stability
      </title>

      <para>
        The key/value pairs defined in the GDM configuration files and
        the location of these files are considered &quot;stable&quot; interfaces
        and should only change in ways that are backwards compatible.  Note that
        this includes functionality like the GDM scripts (Init, PreSession,
        PostSession, PostLogin, XKeepsCrashing, etc.); directory locations
        (ServAuthDir, PidFile, etc.), system applications (SoundProgram), etc.
        Some configuration values depend on OS interfaces may need to be
        modified to work on a given OS.  Typical examples are HaltCommand,
        RebootCommand, CustomCommands, SuspendCommand, StandardXServer, Xnest,
        SoundProgram, and the &quot;command&quot; value for each
        &quot;server-foo&quot;.
      </para>

      <para>
        Note: distributions often change the default values of keys to support
        their platform.  Command-line interfaces for GDM programs installed to
        <filename>&lt;bin&gt;</filename> and <filename>&lt;sbin&gt;</filename>
        are considered stable.  Refer to your distribution documentation to see
        if there are any distribution-specific changes to these GDM interfaces
        and what support exists for them.
      </para>

      <para>
        As of the GDM 2.15 development series, some one-dash arguments are no
        longer supported.  This includes the &quot;-xdmaddress&quot;,
        &quot;-clientaddress&quot;, and &quot;-connectionType&quot; arguments
        used by <command>gdmchooser</command>.  These arguments have been
        changed to now use two dashes.
      </para>

      <para>
        If issues are discovered that break compatibility, please file a bug
        with an &quot;urgent&quot; priority.
      </para>
    </sect2>

    <sect2 id="daemonov">
      <title>The GDM Daemon</title>
      
      <para>
        The GDM daemon is responsible for managing displays on the system.
        This includes authenticating users, starting the user session, and
        terminating the user session.  GDM is configurable and the ways it can
        be configured are described in the &quot;Configuring GDM&quot; section
        of this document.  The <filename>Init</filename>,
        <filename>PostLogin</filename>, <filename>PreSession</filename>, 
        and <filename>PostSession</filename> scripts discussed below are 
        discussed in this &quot;Configuring GDM section&quot;.
      </para>

      <para>
        The GDM daemon supports a UNIX domain socket protocol which can be used
        to control aspects of its behavior and to query information.  This
        protocol is described in the &quot;Controlling GDM&quot; section of
        this document.  
      </para>

      <para>
        GDM can be asked to manage a display a number of ways.  Local displays
        are always managed when GDM starts and will be restarted when a user's
        session is finished.  Displays can be requested via XDMCP, flexible
        displays can be requested by running the
        <command>gdmflexiserver</command> command.  Displays that are started
        on request are not restarted on session exit.  GDM also provides the
        <command>gdmdynamic</command> command to allow easier management of
        displays on a multi-user server.  These display types are discussed
        further in the next section.  
      </para>
        
      <para>
        When the GDM daemon is asked to manage a display, it will fork an
        X server process, then run the <filename>Init</filename> script as the
        root user, and start the login GUI dialog as a slave process on the
        display.  GDM can be configured to use either
        <command>gdmgreeter</command> (the default) or
        <command>gdmlogin</command> as the GUI dialog program.  The
        <command>gdmlogin</command> program supports accessibility while the
        <command>gdmgreeter</command> program supports greater themeability.
        The GUI dialog is run as the unpriviledged &quot;gdm&quot; user/group
        which is described in the &quot;Security&quot; section below.  The GUI
        dialog communicates with the daemon via a sockets protocol and via
        standard input/output.  The slave, for example passes the username and
        password information to the GDM daemon via standard input/output so
        the daemon can handle the actual authentication.
      </para>

      <para>
        The login GUI dialog screen allows the user to select which session
        they wish to start and which language they wish to use.  Sessions are
        defined by files that end in the .desktop extension and more
        information about these files can be found in the
        &quot;Configuration&quot; section.  The user enters their name and
        password and if these successfully authenticate, GDM will start the
        requested session for the user.  It is possible to configure GDM to
        avoid the authentication process by turning on the Automatic or Timed
        Login features in the GDM configuration.  The login GUI can also be
        configured to provide additional features to the user, such as the
        Face Browser; the ability to halt, restart, or suspend the system;
        and/or edit the login configuration (after entering the root password).
      </para>

      <para> 
        GDM, by default, will use Pluggable Authentication Modules (PAM) for
        authentication, but can also support regular crypt and shadow passwords
        on legacy systems.  After authenticating a user, the daemon runs the
        <filename>PostLogin</filename> script as root, and forks a slave
        process to start the requested session.  This slave process runs the
        <filename>PreSession</filename> script as root, sets up the user's
        environment, and starts the requested session.  GDM keeps track of the
        user's default session and language in the user's
        <filename>~/.dmrc</filename> and will use these defaults if the user
        did not pick a session or language in the login GUI.  On Solaris, GDM
        (since version 2.8.0.3) uses the SDTLOGIN interface after user
        authentication to tell the X server to be restarted as the user instead
        of as root for added security.  When the user's session exits, the GDM
        daemon will run the <filename>PostSession</filename> script as root.
      </para>

      <para>
        Note that, by default, GDM uses the &quot;gdm&quot; service name for
        normal login and the &quot;gdm-autologin&quot; service name for
        automatic login.  The <filename>PamStack</filename> configuration
        option can be used to specify a different service name.  For example,
        if &quot;foo&quot; is specified, then GDM will use the &quot;foo&quot;
        service name for normal login and &quot;foo-autologin&quot; for
        automatic login. 
      </para>

      <para>
        For those looking at the code, the gdm_verify_user function in 
        <filename>daemon/verify-pam.c</filename> is used for normal login
        and the gdm_verify_setup_user function is used for automatic login.
      </para>
    </sect2>

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

      <para>
        GDM supports three different display types: static (local) displays,
        flexible (on-demand) displays, and XDMCP (remote) displays.  The
        &quot;X Server Definitions&quot; and the &quot;Local Static X Display
        Configuration&quot; subsections of the &quot;Configuration&quot;
        section explains how these various types of displays are defined in
        the GDM configuration file.
      </para>

      <para>
        Local static displays are always started by the daemon, and when they
        die or are killed, they are restarted.  GDM can run as many of these
        as needed.  GDM can also manage displays on which it does not manage a
        GUI login, thus GDM can be used for supporting X terminals.
      </para>

      <para>
        Flexible, or on demand displays, are started via the socket protocol
        with the <command>gdmflexiserver</command> command.  This feature is
        only available to users logged in on the console and will display a new
        login screen.  If a flexible display has previously been started on
        the console, running <command>gdmflexiserver</command> again will
        display a menu allowing users to switch back to a previous session
        or start a new flexible session.  The <command>gdmflexiserver</command>
        locks the current session before starting a new flexible display, so
        the user's password must be entered before returning to an existing
        session.  The <command>gdmflexiserver</command> command can also be
        used to launch nested <command>Xnest</command> display.  These are
        launched in a window in the user's current session.  Nested displays
        can be started even if not logged into the console and are started by 
        running the <command>gdmflexiserver -n</command> command.  Flexible
        displays are not restarted when the user session ends.  Flexible
        displays require virtual terminal (VT) support in the kernel, and will
        not be available if not supported (such as on Solaris).  Nested
        displays require that the X server supports Xnest.
      </para>

      <para>
        The last display type is the XDMCP remote displays which are described
        in the next section.  Remote hosts can connect to GDM and present the
        login screen if this is enabled.  Some things are different for
        remote sessions.  For example, the Actions menu which allows you to
        shut down, restart, suspend, or configure GDM are not shown.
      </para>

      <para>
        Displays started via the <command>gdmdynamic</command> command are
        treated as local displays, so they are restarted automatically on
        when the session exits.  This command is intended to more effectively
        manage the displays on a multi-user server (many displays connected
        to a single server).
      </para>
    </sect2>

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

      <para>
        The GDM daemon can be configured to listen for and manage X Display
        Manage Protocol (XDMCP) requests from remote displays.  By default
        XDMCP support is turned off, but can be enabled if desired.  If GDM is
        built with TCP Wrapper support, then the daemon will only grant access
        to hosts specified in the GDM service section in the TCP Wrappers
        configuration file.
      </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.  Do not change them unless you
        know what you are doing.
      </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>
        Refer to the &quot;Security&quot; section for information about
        security concerns when using XDMCP.
      </para>
    </sect2>

    <sect2 id="secureremote">
      <title>
        Securing Remote Connection Through SSH
      </title>
      <para>
        As explained in the &quot;Security&quot; section, XDMCP does not use
        any kind of encryption and as such is inherently insecure.  As XDMCP
        uses UDP as a network transport layer, it is not possible to simply
        secure it through an SSH tunnel.
      </para>

      <para>
        To remedy this problem, gdm can be configured at compilation-time with
        the option --enable-secureremote, in which case gdm proposes as a
        built-in session a session called &quot;Secure Remote Connection&quot;.
        Starting such a session allows the user to enter the name or the
        address of the host on which to connect; provided the said host runs an
        SSH server, the user then gets connected to the server on which the
        default X session is started and displayed on the local host.
      </para>
      
      <para>
        Using this session allows a much more secure network connection and
        only necessitates to have an SSH server running on the remote host.
      </para>
    </sect2>

    <sect2 id="gtkgreeter">
      <title>The GTK+ Greeter</title>

      <para>
        The GTK+ 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.
        This greeter has full accessibility support, and should be used
        by users with accessibility needs.
      </para>

      <para>
        The text entry field is used for entering logins, passwords,
        passphrases etc. <command>gdmlogin</command> 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, halt/restart/suspend the computer, configure GDM
        (given the user knows the root password), change the GTK+ theme, or
        start an XDMCP chooser.
      </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="themedgreeter">
      <title>The Themed Greeter</title>

      <para>
        The Themed 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 application or by setting the
        <filename>GraphicalTheme</filename> configuration key.  The Themed
        Greeter is much like the GTK+ Greeter in that it is controlled by
        the underlying daemon, is stateless, and is controlled by the
        daemon using the same simple protocol.
      </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 GTK+ Greeter.  The theme can include buttons
        that allow the user to select an appropriate locale/language,
        halt/restart/suspend the computer, configure GDM (given the user
        knows the root password), or start an XDMCP chooser.
      </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 wish to do some action allowed by the GDM configuration.
      </para>
    </sect2>

    <sect2 id="facebrowser">
      <title>The GDM Face Browser</title>

      <para>
        GDM supports a face browser which will display a list of users who
        can login and an icon for each user.  This feature can be used with
        the GTK+ Greeter if the <filename>Browser</filename> configuration
        option is set to &quot;true&quot;.  This feature can be used with
        the Themed Greeter if using a GDM theme which includes a
        &quot;userlist&quot; item type is defined, such as
        &quot;happygnome-list&quot;
      </para>

      <para>
        By default, the face browser is disabled since revealing usernames on
        the login screen is not appropriate on many systems for security 
        reasons.  Also GDM requires some setup to specify which users should
        be visible.  Setup can be done on the &quot;Users&quot; tab in
        <command>gdmsetup</command>.  This feature is most practical to use
        on a system with a smaller number of users.
      </para>

      <para>
        The icons used by GDM can be installed globally by the sysadmin or can
        be located in the users' home directories.  If installed globally
        they should be in the <filename>&lt;share&gt;/pixmaps/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.  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 do not have be be
        readable by the &quot;gdm&quot; user, but root.
      </para>

      <para>
        Users may run the <command>gdmphotosetup</command> command to 
        configure the image to use for their userid.  This program properly
        scales the file down if it is larger than the
        <filename>MaxIconWidth</filename> or 
        <filename>MaxIconHeight</filename> configuration options and places the
        icon in a file called <filename>~/.face</filename>.  Although
        <command>gdmphotosetup</command> scales user images automatically,
        this does not guarantee that user images are properly scaled since
        a user may create their <filename>~/.face</filename> file by hand.
      </para>
        
      <para>
        GDM will first look for the user's face image in
        <filename>~/.face</filename>.  If not found, it will try 
        <filename>~/.face.icon</filename>.  If still not found, it will
        use the value defined for &quot;face/picture=&quot; in the 
        <filename>~/.gnome2/gdm</filename> file.  Lastly, it will try
        <filename>~/.gnome2/photo</filename> and 
        <filename>~/.gnome/photo</filename> which are deprecated and
        supported for backwards compatibility.
      </para>

      <para>
        If a user has no defined face image, GDM will use the
        &quot;stock_person&quot; icon defined in the current GTK+ theme.  If no
        such image is defined, it will fallback to the image specified in the
        <filename>DefaultFace</filename> configuration option, normally
        <filename>&lt;share&gt;/pixmaps/nobody.png</filename>.
      </para>
      
      <para>
        Please note that loading and scaling face icons located in user home
        directories can be a very time-consuming task.  Since it not 
        practical to load images over NIS or NFS, GDM does not attempt to
        load face images from remote home directories.  Furthermore, GDM will
        give up loading face images after 5 seconds of activity and will
        only display the users whose pictures it has gotten so far.  The
        <filename>Include</filename> configuration option can be used to
        specify a set of users who should appear on the face browser.  As
        long as the users to include is of a reasonable size, there should
        not be a problem with GDM being unable to access the face images.
        To work around such problems, it is recommended to place face images
        in the directory specified by the <filename>GlobalFaceDir</filename>
        configuration option.
      </para>

      <para>
        To control the users who get displayed in the face browser, there are
        a number of configuration options that can be used.  If the
        <filename>IncludeAll</filename> option is set to true, then the
        password file will be scanned and all users will be displayed.  If
        <filename>IncludeAll</filename> option is set to false, then the
        <filename>Include</filename> option should contain a list of users
        separated by commas.  Only the users specified will be displayed.
        Any user listed in the <filename>Exclude</filename> option and users
        whose UID's is lower than <filename>MinimalUID</filename> will be
        filtered out regardless of the <filename>IncludeAll</filename>
        setting.  <filename>IncludeAll</filename> is not recommended
        for systems where the passwords are loaded over a network (such as
        when NIS is used), since it can be very slow to load more than a
        small number of users over the network..
      </para>

      <para>
        When the browser is turned on, valid usernames on the computer are
        inherently exposed to a potential intruder.  This may be a bad idea if
        you do not know who can get to a login screen.  This is especially
        true if you run XDMCP (turned off by default).
      </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, which can be useful for tracking down problems
        if GDM is not working properly.  This can 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>&lt;var&gt;/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>
        You can suppress the 10 second warning by returning code 66 from the
        <filename>Xsession</filename>script or from your session binary (the
        default <filename>Xsession</filename> script propagates those codes
        back).  This is useful if you have some sort of special logins for
        which it is not an error to return less then 10 seconds later, or if
        you setup the session to already display some error message and the
        GDM message would be confusing and redundant.
      </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 user's 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 unnecessarily stay around.
      </para>
    </sect2>

    <sect2 id="fileaccess">
      <title>Accessing Files</title>

      <para>
        In general GDM is very reluctant regarding reading/writing of user
        files (such as the <filename>~/.dmrc</filename>,
        <filename>~/.face</filename>,
        <filename>~/.xsession-errors</filename>, and
        <filename>~/.Xauthority</filename> files).  For instance it refuses to
        access anything but regular files.  Links, sockets and devices are
        ignored.  The value of the <filename>RelaxPermissions</filename>
        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
        the directory specified by the <filename>UserAuthFBDir</filename>
        configuration setting (<filename>/tmp</filename> by default).
      </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
        home directories, scaling and rendering face icons can take a long
        time.
      </para>
    </sect2>

    <sect2 id="performance">
      <title>GDM Performance</title>

      <para>
        To speed performance it is possible to build GDM so that it will
        preload libraries when GDM first displays a greeter program.  This
        has been shown to speed first time login since these libraries can
        be loaded into memory while the user types in their username and
        password.
      </para>

      <para>
        To use this feature, configure GDM with the
        <command>--with-prefetch</command> option.  This will cause GDM to
        install the <command>gdmprefetch</command> program to the
        <filename>libexecdir</filename> directory, install the
        <filename>gdmprefetchlist</filename> to the
        <filename>&lt;etc&gt;/gdm</filename> directory, and set the
        <filename>PreFetchProgram</filename> configuration variable so that the
        <command>gdmprefetch</command> program is called with the default
        <filename>gdmprefetchlist</filename> file.  The default
        <filename>gdmprefetchlist</filename> file was optimized
        for a GNOME desktop running on Solaris, so may need fine-tuning on
        other systems.  Alternative prefetchlist files can be contributed
        to the &quot;gdm&quot; category in
        <ulink type="http" url="http://bugzilla.gnome.org/">bugzilla.gnome.org</ulink>,
        so that they can be included in future GDM releases.
      </para>
    </sect2>
  </sect1>

  <sect1 id="security">
    <title>Security</title>

    <sect2 id="PAM">
      <title>
        PAM
      </title>

      <para>
        GDM uses PAM for login authentication, though if your machine does not
        support PAM you can build GDM to work with the password database and
        the crypt library function.
      </para>

      <para>
        PAM stands for Pluggable Authentication Module, and is used by most
        programs that request authentication on your computer.  It allows the
        administrator to configure different authentication behavior for
        different programs.
      </para>

      <para>
        Some GDM features (like turning on automatic login) may require that
        you update your PAM configuration.  PAM configuration has different,
        but similar, interfaces on different operating systems, so check your
        pam.d or pam.conf man page for details.  Be sure that you read the
        PAM documentation (e.g. pam.d/pam.conf man page) and are comfortable
        with the security implications of any changes you intend to make to
        your configuration.
      </para>

      <para>
        If there is no entry for GDM in your system's PAM configuration file,
        then features like automatic login may not work.  Not having an entry
        will cause GDM to use default behavior, conservative settings are
        recommended and probably shipped with your distribution.
      </para>

      <para>
        If you wish to make GDM work with other types of authentication
        mechanisms (such as a SmartCard), then you should implement this by
        using a PAM service module for the desired authentication type rather
        than by trying to modify the GDM code directly.  Refer to the PAM
        documentation on your system.  This issue has been discussed on the
        <address><email>gdm-list@gnome.org</email></address> mail list,
        so you can refer to the list archives for more information.
      </para>
    </sect2>

    <sect2 id="gdmuser">
      <title>The GDM User</title>

      <para>
        For security reasons a dedicated user and group id are required for
        proper operation!  The need to be able to write Xauth files is why user
        &quot;nobody&quot; is not appropriate for gdm.
      </para>

      <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 <command>gdmgreeter</command> and
        <command>gdmlogin</command>.  These are configured via the
        <filename>User</filename> and <filename>Group</filename>
        configuration options in the GDM configuration files.  The user and
        group should be created before running &quot;make install&quot;.  By
        default GDM assumes the user and the group are called &quot;gdm&quot;. 
      </para>

      <para>
        This userid is used to run the GDM GUI programs required for login.
        All functionality that requires root authority is done by the GDM
        daemon process.  This design ensures that if the GUI programs are
        somehow exploited, only the dedicated user privileges are available.
      </para>

      <para>
        It should however be noted that the GDM user and group have some
        privileges that make them somewhat dangerous.  For one, they have
        access to the X server authorization directory.  It must be able to
        read and write Xauth keys to <filename>&lt;var&gt;/lib/gdm</filename>.
        This directory should have root:gdm ownership and 1770 permissions.
        Running &quot;make install&quot; will set this directory to these
        values.  The GDM daemon process will reset this directory to proper
        ownership/permissions if it is somehow not set properly.
      </para>

      <para>
        The danger is that someone who gains the GDM user/group privileges 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>.  Users who
        gain access to the &quot;gdm&quot; user could also modify the Xauth
        keys causing Denial-Of-Service attacks.  Also if a person gains the
        ability to run programs as the user &quot;gdm&quot;, it would be
        possible to snoop on running GDM processes, including usernames and
        passwords as they are being typed in.  
      </para>

      <para>
        Distributions and system administrators using GDM are expected to setup
        the dedicated user properly.  It is recommended that this userid be
        configured to disallow login and to not have a default shell.
        Distributions and system administrators should set up the filesystem to
        ensure that the GDM user does not have read or write access to
        sensitive files.
      </para>
    </sect2>

    <sect2 id="xauth">
      <title>X Server Authentication Scheme</title>
 
      <para>
        The X 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
        directory 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 X 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>
        GDM only supports the MIT-MAGIC-COOKIE-1 X server authentication
        scheme.  Normally little is gained from the other schemes, and no
        effort has been made to implement them so far.  Be especially
        careful about using XDMCP because the X server authentication cookie
        goes over the wire as clear text.  If snooping is possible, then an
        attacker could simply snoop your authentication password as you log in,
        regardless of the authentication scheme being used.  If snooping is
        possible and undesirable, then you should use ssh for tunneling an X
        connection rather then using XDMCP.  You could think of XDMCP as a sort
        of graphical telnet, having the same security issues.
      </para>

      <para>
        On the upside, GDM's random number generation is very conservative and
        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, and other random information
        (possibly using <filename>/dev/audio</filename> or
        <filename>/dev/mem</filename> if hardware random generators are not
        available) to create a large buffer and then run MD5 digest on this.
        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).  So be careful
        about where you use remote X display.
      </para>
    </sect2>

    <sect2 id="firewall">
      <title>Firewall Security</title>

      <para>
        Even though GDM tries to outsmart potential attackers trying to take
        advantage of XDMCP, it is still advised that you block the XDMCP port
        (normally UDP port 177) on your firewall unless you really need it.
        GDM guards against DoS (Denial of Service) 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 DoS via XDMCP then a webserver.
      </para>

      <para>
        It is also wise to block all of the X Server ports.  These are TCP
        ports 6000 + the display number of course) on your firewall.  Note that
        GDM will use display numbers 20 and higher for flexible on-demand
        servers.
      </para>

      <para>
         X is not a very safe protocol for leaving on the net, and XDMCP is
         even less safe.  
      </para>
    </sect2>

    <sect2 id="nfssecurity">
      <title>GDM Security With NFS</title>

      <para>
        Note that NFS traffic really goes &quot;over the wire&quot; and thus
        can be snooped.  When accessing the user's X authorization file
        (<filename>~/.Xauthority</filename>), GDM will try to open the file
        for reading as root.  If it fails, GDM will conclude that it is on an
        NFS mount and it will automatically use
        <filename>UserAuthFBDir</filename>, which by default is set to
        <filename>/tmp</filename>.  This behavior can be changed by setting the
        <filename>NeverPlaceCookiesOnNFS</filename> in the
        <filename>[security]</filename> section to false.
      </para>
    </sect2>

    <sect2 id="xdmcpsecurity">
      <title>XDMCP Security</title>

      <para>
        Even though your display is protected by cookies, XEvents and thus
        keystrokes typed when entering passwords will still go over the wire in
        clear text.  It is trivial to capture these.
      </para>

      <para>
        XDMCP is primarily useful for running thin clients such as in terminal
        labs.  Those thin clients will only ever need the network to access
        the server, and so it seems like the best security policy 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>

      <para>
        The above sections &quot;X Server Authentication Scheme&quot; and
        &quot;Firewall Security&quot; also contain important information about
        using XDMCP securely.  The next section also discusses how to set up
        XDMCP access control.
      </para>

      <para>
        To workaround the inherent insecurity of XDMCP, gdm proposes a default
        built-in session that uses SSH to encrypt the remote connection.  See
        the section &quot;Securing remote connection through SSH&quot; above.
      </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 and verify that they work.
      </para>

      <para>
        You should use the daemon name <command>gdm</command> in the
        <filename>&lt;etc&gt;/hosts.allow</filename> and
        <filename>&lt;etc&gt;/hosts.deny</filename> files.  For example to 
        deny computers from <filename>.evil.domain</filename> from logging in,
        then add
      </para>
<screen>
gdm: .evil.domain
</screen>
      <para>
        to <filename>&lt;etc&gt;/hosts.deny</filename>.  You may also need
        to add
      </para>
<screen>
gdm: .your.domain
</screen>
      <para>
        to your <filename>&lt;etc&gt;/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>
    </sect2>
  </sect1>

  <sect1 id="consolekit">
    <title>Support for ConsoleKit</title>

    <para>
      GDM includes support for publishing user login information with the user and login
      session accounting framework known as ConsoleKit.  ConsoleKit is able to keep track
      of all the users currently logged in.  In this respect, it can be used as a replacement
      for the utmp or utmpx files that are available on most Unix-like operating systems.
    </para>

    <para>
      When GDM is about to create a new login process for a user it will call a privileged
      method of ConsoleKit in order to open a new session for this user.  At this time
      GDM also provides ConsoleKit with information about this user session such as: the user ID,
      the X11 Display name that will be associated with the session, the host-name from which the
      session originates (useful in the case of an XDMCP session), whether or not this session
      is local, etc.  As the entity that initiates the user process, GDM is in a unique position
      know and to be trusted to provide these bits of information about the user session.  The use
      of this privileged method is restricted by the use of D-Bus system message bus security policy.
    </para>

    <para>
      In the case where a user with an existing session and has authenticated at GDM and requests to
      resume that existing session GDM calls a privileged method of ConsoleKit to unlock that
      session.  The exact details of what happens when the session receives this unlock signal is
      undefined and session-specific.  However, most sessions will unlock a screensaver in response.
    </para>

    <para>
      When the user chooses to log out, or if GDM or the session quit unexpectedly the user session
      will be unregistered from ConsoleKit.
    </para>

    <para>
      If support for ConsoleKit is not desired it can be disabled at build time using the
      --with-console-kit=no option when running configure.
    </para>

  </sect1>

  <sect1 id="gdmsetupusage">
    <title>Using gdmsetup To Configure GDM</title>

    <para>
      The <command>gdmsetup</command> application can be used to configure GDM.
      If you believe running root-owned GUI's causes security risk, then you
      would want to always edit the files by hand and not use
      <command>gdmsetup</command>.  Editing the files by hand is explained in
      the &quot;Configuration&quot; section of this document.  Note that 
      <command>gdmsetup</command> does not support changing of all
      configuration variables, so it may be necessary to edit the files by
      hand for some configurations.
    </para>

    <para>
      The <command>gdmsetup</command> program has five tabs: Local, Remote,
      Accessibility, Security, and Users, described below.  In parenthesis is
      information about which GDM configuration key is affected by each GUI
      choice.  Refer to the &quot;Configuration&quot; section of this manual
      and the comments in the &lt;share&gt;/gdm/defaults.conf file for
      additional details about each key.
    </para>

    <sect2 id="gdmsetuplocaltab">
      <title>Local Tab</title>
     
      <para>
        The Local tab is used for controlling the appearance of GDM for
        local/static displays (non-XDMCP remote connections).  The choices
        available in this tab depend on the setting of the &quot;Style&quot;
        combobox.  This combobox is used to determine whether the 
        &quot;Plain&quot; or &quot;Themed&quot; greeter GUI is used.  The
        differences between these greeter programs are explained in the
        &quot;Overview&quot; section of this document.
      </para>

      <para>
        If the &quot;Style&quot; choice is &quot;Plain&quot;, then GDM will
        use the <command>gdmlogin</command> program as the GUI
        (daemon/Greeter).  When this choice is selected,
        <command>gdmsetup</command> allows the user to select whether the
        background is an image or solid color (greeter/BackgroundType).  If
        image is selected, there is a file selection button to pick the image
        file (greeter/BackgroundImage) and a checkbox to scale the image to fit
        the screen (greeter/BackgroundImageScaleToFit).  If solid color is
        selected, there is a button available to allow the color selection
        (greeter/BackgroundColor).  Also, the user may select the logo image
        that appears in gdmlogin (greeter/Logo).
      </para>

      <para>
        If the &quot;Style&quot; choice is &quot;Plain with face browser&quot;,
        then the <command>gdmlogin</command> program is used as the GUI
        (daemon/Greeter) and the face browser is turned on (greeter/Browser).
        The Face Browser is explained in the Overview section.  Otherwise,
        the choices are the same as when the &quot;Style&quot; choice is
        &quot;Plain&quot;.  Additional setup in the Users tab may be 
        necessary to choose which users appear in the Face Browser.
      </para>

      <para>
        If the &quot;Style&quot; choice is &quot;Themed&quot;, then the 
        <command>gdmgreeter</command> program is used as the GUI
        (daemon/Greeter).  When this choice is selected,
        <command>gdmsetup</command> allows the user to select the theme to be
        used (greeter/GraphicalTheme).  Note that the checkbox to the left
        of the theme's name must be checked for a theme to be selected.
        Clicking on the theme, but not selecting the checkbox will highlight
        the theme and the &quot;Remove&quot; button can be used to delete
        the theme.  Information about the theme's author and copyright are
        shown for the highlighted theme.  The &quot;Add&quot; button can be
        used to add new themes to the system.  To turn on the Face Browser, a
        theme which includes a Face Browser must be selected, such as 
        happygnome-list.  The &quot;Background color&quot; displayed when
        GDM starts (and if the theme has transparent elements) can also be
        selected (greeter/GraphicalThemedColor).  The &quot;Theme&quot; combo
        box may be set to &quot;Random from selected&quot; if you want a random
        theme to be used for each login (greeter/GraphicalThemeRand and
        greeter/GraphicalThemes).  To use random themes, select each theme that
        you wish to be used.  By default this combobox is set to
        &quot;Selected only&quot;, so that only a single theme can be selected
        and be used.
      </para>

      <para>
        Regardless of the &quot;Style&quot; choice, the user may also select
        whether the Actions menu is visible (greeter/SystemMenu), whether the
        Actions menu includes the choice to start <command>gdmsetup</command>
        (greeter/ConfigAvailable), and whether the Action menu includes the
        choice to start <command>gdmchooser</command> to run a remote XDMCP
        login session (greeter/ChooserButton).  Note that the root password
        must be entered to start <command>gdmsetup</command> from the login
        screen if it is enabled.   Also the Welcome message displayed for local
        sessions may be selected (greeter/DefaultWelcome and greeter/Welcome). 
        The Welcome message can contain the character sequences described in
        the &quot;Text Node&quot; section of the &quot;Themed Greeter&quot;
        section of this manual.
      </para>
    </sect2>

    <sect2 id="gdmsetupremotetab">
      <title>Remote Tab</title>

      <para>
        The Remote tab controls the appearance of the GDM for users logging
        in via XDMCP.  By default XDMCP is disabled, and users should be 
        comfortable with the XDMCP-related sections of the Security section
        of this document before enabling it.  This tab includes a
        &quot;Style&quot; combobox which can be used to turn on XDMCP and
        control the appearance of GDM for remote users (gui/RemoteGreeter
        and xdmcp/Enable).  This combobox may be set to &quot;Remote login
        disabled&quot; or &quot;Same as Local&quot;.  If the Local tab
        is set to &quot;Plain&quot; or &quot;Plain with Face Browser&quot;,
        then the user may also select &quot;Themed&quot;.  If the Local tab
        is set to &quot;Themed&quot;, then the user may also select
        &quot;Plain&quot; or &quot;Plain with face browser&quot;.  It is
        recommended that the &quot;Plain&quot; GUI be used for remote
        connections since it is more lightweight and tends to have better
        performance across a network.
      </para>

      <para>
        If Remote login is enabled, then the user can specify the remote
        Welcome Message to be displayed (greeter/DefaultRemoteWelcome and 
        greeter/RemoteWelcome).  This welcome message is separate from the
        Local welcome message and can have a different value.  The Welcome
        message can contain the character sequences described in the
        &quot;Text Node&quot; section of the &quot;Themed Greeter&quot;
        section of this manual.
      </para>

      <para>
        If the &quot;Style&quot; choice is &quot;Same as Local&quot; and the
        local selection is &quot;Plain&quot; or &quot;Plain with face
        browser&quot;, then the user may select whether background images
        should be displayed for remote logins
        (greeter/BackgroundRemoteOnlyColor).
      </para>

      <para>
        If the &quot;Style&quot; choice is enabled and set to a different
        value than the Local tab, then the user has the same configuration
        choices as found on the Local tab except that the System Menu 
        choices are not available since this is never available for remote
        logins for security purposes.
      </para>

      <para>
        If Remote login is enabled, there is a &quot;Configure XDMCP&quot;
        button which displays a dialog allowing the user to set XDMCP 
        configuration, including whether indirect requests are honored
        (xdmcp/HonorIndirect), UDP port (xdmcp/Port), maximum pending requests
        (xdmcp/MaxPending), maximum pending indirect requests
        (xmdcp/MaxPendingIndirect), maximum remote sessions
        (xdmcp/MaxSessions), maximum wait time (xdmcp/MaxWait), maximum
        indirect wait time (xdmcp/MaxWaitIndirect), displays per host
        (xdmcp/DisplaysPerHost), and ping interval (xdmcp/PingIntervalSeconds).
        The default settings are standard settings and should only be changed
        by someone who understands the ramifications of the change.
      </para>
    </sect2>

    <sect2 id="gdmsetupaccessibilitytab">
      <title>Accessibility Tab</title>

      <para>
        The Accessibility tab is used to turn on Accessibility features in GDM.
        &quot;Enable accessible login&quot; (daemon/AddGtkModules and
        daemon/GtkModulesList) turns on GDM's gesture listeners which are
        explained in the &quot;Accessibility&quot; section of this document.
        There is also a checkbox to allow users to change the theme when using 
        the Plain greeter (gui/AllowGtkThemeChange).  This feature allows GDM
        users to switch the theme to the HighContrast or LowContrast themes if
        needed.  The user may also select whether GDM should play a sound when
        the login screen is ready, when login is successful and when login has
        failed.  File chooser buttons are used to select the sound file to be
        played, and the &quot;Play&quot; button can be used to sample the
        sound.
      </para>
    </sect2>

    <sect2 id="gdmsetupsecuritytab">
      <title>Security Tab</title>

      <para>
        The Security tab allows the user to turn on Automatic and Timed login,
        which user is logged in via an automatic or timed login, and the
        timed login delay (daemon/AutomaticLoginEnable, daemon/AutomaticLogin,
        daemon/TimedLoginEnable, daemon/TimedLogin, and daemon/TimedLoginDelay).
        If automatic login is turned on, then the specified user will
        immediately log in on reboot without GDM asking for username/password.
        If the user logs out of their session, GDM will start and ask for
        username and password to log back in.  If TimedLogin is turned on, then
        GDM will log in to the specified user after a specified number of
        seconds.  The user may enable Timed Login for remote (XDMCP)
        connections by checking the &quot;Allow remote timed logins&quot;
        checkbox.
      </para>

      <para>
        On this tab, the user may select whether the system administrator user
        can log in, and whether the system administrator user can log in
        via remote (XDMCP) connections (security/AllowRoot and
        security/AllowRemoteRoot).  The user may turn on GDM debug 
        (debug/Enable) which causes debug messages to be sent to the system
        log.  Debug should only be used when diagnosing a problem and not be
        left on when not needed.  The &quot;Deny TCP connections to
        Xserver&quot; choice will disable X forwarding if selected
        (security/DisallowTCP).  A login retry delay (security/RetryDelay) can
        be set to cause GDM to wait a number of seconds after a failed login.
      </para>  

      <para>
         The &quot;Configure X Server&quot; button can be used to specify how
         GDM manages each display.  The &quot;Servers&quot; combobox shows what
         server definitions are available (Standard, Terminal, and Chooser by
         default).  Refer to the &quot;X Server Definitions&quot; section of
         the &quot;Configuration&quot; section for more information about how 
         to create new Server Definitions.
      </para>

      <para>
         For any server type, the user may modify the &quot;Server Name&quot;
         (server/name), the &quot;Command&quot; (server/command) to be used to
         launch the Xserver, whether the server type will &quot;Launch&quot;
         (server/chooser) the greeter or chooser GUI after starting the
         Xserver, whether GDM handles this type (normally only set to false
         when logging into a Terminal session type), and whether the session
         type supports &quot;Flexible&quot; (server/flexible) sessions.
      </para>

      <para>
         The &quot;Servers To Start&quot; section shows what server type is
         displayed for each display on the machine.  Users may click on the
         &quot;Add/Modify&quot; button to add a new display to the list or to
         modify a selected display.  This simply corresponds each physical
         display with the Server Definition to be used for managing that
         display.  The &quot;Remove&quot; button may be used to remove a
         display from the list.
      </para>
    </sect2>

    <sect2 id="gdmsetupuserstab">
      <title>Users Tab</title>

      <para>
         The Users tab controls which users appear in the Face Browser.  If the
         &quot;Include all users from /etc/password&quot; checkbox is selected,
         then all users (with a userid above greeter/MinimalUID and not in the
         Exclude list) are displayed.  If this checkbox is not selected, then
         users must be added to the &quot;Include&quot; list.  Users in the
         &quot;Exclude&quot; list are never displayed.  The &quot;Add&quot; and
         &quot;Remove&quot; buttons are used to add a new user to the list or
         remove a selected user from the list.  The &quot;Apply User
         Changes&quot; button must be pressed after the &quot;Include&quot; and
         &quot;Exclude&quot; lists have been modified.  The left and right
         arrow buttons between the &quot;Include&quot; and &quot;Exclude&quot;
         lists can be used to move a selected user from one list to the other.
      </para>
    </sect2>
  </sect1>

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

    <para> 
      GDM has powerful configuration management.  System configuration is stored
      in <filename>&lt;share&gt;/gdm/defaults.conf</filename> and the intention
      is that this file can be stored on a shared filesystem so that sysadmins
      can have a single file to modify to control configuration for multiple
      machines.  Also GDM distributions may patch this file on update to 
      improve usability, improve security, etc.  Configuration may be customized
      for a specific machine by editing the
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> file to include an
      override for a specific key.  Those parameters in the &quot;gui&quot;,
      &quot;greeter&quot; sections, and the security/PamStack key may be
      customized per-display by specifying them in a file named
      <filename>&lt;etc&gt;/gdm/custom.conf&lt;display num&gt;</filename>.
      For example, configuration overrides for display &quot;:103&quot; would be
      stored in the file <filename>&lt;etc&gt;/gdm/custom.conf:0</filename>.
      Per-display configuration is supported in GDM 2.14.6 and later.
    </para>

    <para>
      The <command>gdmsetup</command> is a GUI program you can use to edit the
      GDM configuration.  This program may also be launched directly from the
      login screen if the greeter/ConfigAvailable key is set to &quot;true&quot;
      Not all keys in the GDM configuration file are supported in the GUI, so
      you may need to edit the configuration files by hand to edit these keys.
      If you believe running root-owned GUI's causes security risk, then you
      would want to always edit the files by hand.  This program does not
      support setting per-display configuration, so per-display configuration
      files must be set up by hand.
    </para>

    <para>
      Distributions should edit the
      <filename>&lt;share&gt;/gdm/defaults.conf</filename> file to establish
      the default values so these are preserved as defaults and not modified
      by users modifying their personal configuration file
      <filename>&lt;etc&gt;/gdm/custom.conf</filename>.
    </para>

    <para>
      If you want to change configuration by hand, edit the
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> file and make
      sure the keyname=value pair you want is included in the appropriate
      section.  For example, to change the &quot;Greeter&quot; key in the
      &quot;daemon&quot; section, make sure the daemon section of the
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> file has the value
      like in this example.  
    </para>

<screen>
[daemon]
Greeter=/usr/lib/gdmgreeter
</screen>

    <para>
      The configuration files (especially the
      <filename>&lt;share&gt;/gdm/defaults.conf</filename> and
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> files) contain
      useful comments and examples, so read them for more information about
      changing your configuration.  GDM considers lines that start with the
      &quot;#&quot; character a comment, and these lines will be ignored by
      GDM.  Some keys in the <filename>&lt;share&gt;/gdm/defaults.conf</filename>
      are commented out while others are set.  Commented out values show the
      default value.
    </para>

    <para> 
      The <filename>&lt;share&gt;/gdm/defaults.conf</filename> file contains
      the default configuration choices for GDM, and should not be modified by
      the user.  The <filename>&lt;etc&gt;/gdm/custom.conf</filename> file
      is where users may specify their custom configuration choices.
      Configuration options specified in the
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> file override the
      values in the main <filename>&lt;share&gt;/gdm/defaults.conf</filename>
      file.   Running the <command>gdmsetup</command> command will cause the
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> to be modified with
      the user's configuration choices and will cause any running GDM GUI 
      programs to automatically update.  Previous to version 2.13.0.4
      GDM only supported the <filename>&lt;etc&gt;/gdm/gdm.conf</filename>
      file, so if using an older version of GDM just edit that file directly.
    </para>

    <para>
      The location of the configuration files may be controlled via the
      <command>--with-defaults-conf</command> and
      <command>--with-custom-conf</command> configuration options.  The GDM
      daemon --config option may also be used to specify the configuration
      file location.  The GDM daemon must be restarted to change the
      configuration file being used.
    </para>

    <para> 
      <filename>&lt;share&gt;/gdm/factory-defaults.conf</filename> is the
      configuration file as shipped with the daemon.  This can be useful for
      to see if the <filename>&lt;share&gt;/gdm/defaults.conf</filename> file
      has been changed.
    </para>

    <para>
      The other GDM configuration files are located, by default, in the
      <filename>&lt;etc&gt;/gdm/</filename> folder or its subdirectories.
      However, the location of all configuration files are defined in 
      the GDM configuration files, so the sysadmin may choose to locate these
      files in any location. 
    </para>

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

<screen>
locale.alias
Xsession
XKeepsCrashing
modules/
Init/
PostLogin/
PreSession/
PostSession/
</screen>

    <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 user's choice of session.  Note that the session
      script is typically started via the <filename>desktop</filename>
      file associated with the session the user has picked.  Some 
      sessions may start the user's session via a different mechanism than
      the <filename>Xsession</filename> script, so please check the
      appropriate <filename>desktop</filename> before assuming a session
      startup issue is being caused by this file.
    </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 application provided the person on the console knows the root
      password.
    </para>

    <para>
      Accessibility modules are configured in the <filename>modules/</filename>
      subdirectory, and are a separate topic.  Read the default files provided,
      they have adequate documentation.  Again normally the default install
      is given in the files with <filename>factory</filename> in their name,
      and those files are not read, they are just there for you so you can
      always revert to default config.
    </para>

    <para>
      Files describing available GDM session follow the freedesktop.org
      desktop file specification and are <filename>.desktop</filename>-style
      files are installed to <filename>&lt;etc&gt;/X11/sessions/</filename>.
      This directory is also read by the KDE desktop manager (KDM) for common
      configuration.  Next the directory
      <filename>&lt;share&gt;/gdm/BuiltInSessions/</filename> is read for
      GDM specific built-in sessions (KDM hardcodes these at time of
      this writing).  Lastly the default setup will also read
      <filename>&lt;share&gt;/xsessions/</filename> (which should be
      <filename>&lt;share&gt;/xsessions/</filename> if you really wish to
      cooperate with KDM) where desktop packages can install their session
      files.  The directories under the <filename>&lt;etc&gt;</filename> should
      be reserved for configuration.  The desktop file specification approach
      makes it easy for package management systems to install window managers
      and different session types without requiring the sysadmin to edit files.
      See the <filename>SessionDesktopDir</filename> configuration key for
      changing the paths.  It used to be that GDM stored its built in
      sessions in <filename>&lt;etc&gt;/dm/Sessions/</filename> but this is
      deprecated as of 2.5.90.0.  Note that prior to version 2.4.4.2 only the
      <filename>&lt;etc&gt;/dm/Sessions/</filename> was being read.
    </para>

    <para>
      A session can be disabled (if it was installed in
      <filename>&lt;share&gt;/xsessions/</filename>) by adding an identically
      named <filename>.desktop</filename> to one of the directories earlier in
      the path (likely <filename>&lt;etc&gt;/X11/sessions</filename>) and using
      <filename>Hidden=true</filename> in that file.
    </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
        displays.  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 applications that are supposed to run alongside with the GDM
        login window. xconsole for instance.  Commands to set the background
        etc. go 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> configuration
        option.
      </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 application.
      </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 path specified by
        <filename>SessionDesktopDir</filename>.  Usually this path is
        <filename>&lt;etc&gt;/X11/sessions/:&lt;etc&gt;/dm/Sessions:/usr/share/xsessions/</filename>.
        The first found file is used.  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 user's 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 user's 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 application.
      </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 Files - <filename>defaults.conf</filename> and
             <filename>custom.conf</filename></title>
      
      <para>
        GDM uses two configuration files:
        <filename>&lt;share&gt;/gdm/defaults.conf</filename>
        and <filename>&lt;etc&gt;/gdm/custom.conf</filename>.  The
        <filename>&lt;share&gt;/gdm/defaults.conf</filename> file contains the
        default configuration choices for GDM, and should not be modified by
        the user.  The <filename>&lt;etc&gt;/gdm/custom.conf</filename>
        file is where users may specify their custom configuration choices.  
        Configuration options specified in the
        <filename>&lt;etc&gt;/gdm/custom.conf</filename> file override the
        values in the <filename>&lt;share&gt;/gdm/defaults.conf</filename>
        file.  If a configuration option is not defined in either file, GDM
        will default to the value described in the comments in the
        <filename>&lt;share&gt;/gdm/defaults.conf</filename> file.
      </para>

      <para>
        Running the <command>gdmsetup</command> command will cause the 
        <filename>&lt;etc&gt;/gdm/custom.conf</filename> to be modified
        with the user's configuration choices.
      </para>

      <para>
        Previous to GDM 2.13.0.4 only the
        <filename>&lt;etc&gt;/gdm/gdm.conf</filename> existed.  If upgrading
        to the new version of GDM, install will check to see if your
        <filename>&lt;etc&gt;/gdm/gdm.conf</filename> file is different than
        your <filename>&lt;etc&gt;/gdm/factory-gdm.conf</filename> file.
        If so, your <filename>&lt;etc&gt;/gdm/gdm.conf</filename> file will be 
        automatically copied to
        <filename>&lt;etc&gt;/gdm/custom.conf</filename> to preserve any
        configuration changes.
      </para>
        
      <para>
        The location of the configuration files may be controlled via the
        <command>--with-defaults-conf</command> and
        <command>--with-custom-conf</command> configuration options.  The
        GDM daemon --config option may instead be used to specify the
        configuration file location.  The GDM daemon must be restarted to
        change the configuration file being used.
      </para>

      <para>
        Both configuration files are divided into sections each containing
        variables that define the behavior for a specific part of the GDM
        suite.  Refer to the comments in the
        <filename>&lt;share&gt;/gdm/defaults.conf</filename> file for
        additional information about each configuration setting.
      </para>

      <para>
        The <filename>&lt;share&gt;/gdm/defaults.conf</filename> and
        <filename>&lt;etc&gt;/gdm/custom.conf</filename> files follow 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 editing 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 <command>gdmgreeter</command> or
                <command>gdmlogin</command> to be launched with additional
                Gtk+ modules. This is useful when extra features are required
                such as accessible login. Note that only &quot;trusted&quot;
                modules should be used to minimize security issues.
              </para>
              <para>
                If true, then the registry daemon
                <command>at-spi-registryd</command>
                will be launched by <command>gdmgreeter</command> or
                <command>gdmlogin</command> starting with version GDM 2.17.
              </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 X 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.  On Solaris, this value is always true, and
                this configuration setting is ignored.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>AlwaysLoginCurrentSession</term>
            <listitem>
              <synopsis>AlwaysLoginCurrentSession=true</synopsis>
              <para>
                If true, then when the user logs in and already has an
                existing session, then they are connected to that session
                rather than starting a new session.  This only works for
                sessions running on VTs (Virtual Terminals) started with
                gdmflexiserver, and not with XDMCP.  Note that VTs are not
                supported on all operating systems.
              </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.  &quot;root&quot; 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 application 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=&lt;etc&gt;/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 &quot;login&quot; for
                the user and so it should source the
                <filename>&lt;etc&gt;/profile</filename> and friends.  The
                standard script shipped with GDM sources the files in this
                order: <filename>&lt;etc&gt;/profile</filename> then
                <filename>~/.profile</filename> then
                <filename>&lt;etc&gt;/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=&lt;bin&gt;/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=&lt;bin&gt;/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>ConsoleCannotHandle</term>
            <listitem>
              <synopsis>ConsoleCannotHandle=am,ar,az,bn,el,fa,gu,hi,ja,ko,ml,mr,pa,ta,zh</synopsis>
              <para>
                These are the languages that the console cannot handle because
                of font issues.  Here we mean the text console, not X.  This
                is only used when there are errors to report and we cannot
                start X.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>ConsoleNotify</term>
            <listitem>
              <synopsis>ConsoleNotify=true</synopsis>
              <para>
                If false, gdm will not display a message dialog on the
                console when an error happens.
              </para>
            </listitem>
          </varlistentry>
                             
          <varlistentry>
            <term>DefaultPath</term>
            <listitem>
              <synopsis>DefaultPath=defaultpath (value set by configure)</synopsis>
              <para>
                Specifies the path which will be set in the user's session.
                This value will be overridden with the value from
                <filename>/etc/default/login</filename> if it contains
                &quot;ROOT=&lt;pathname&gt;&quot;.  If the
                <filename>/etc/default/login</filename> file exists, but
                contains no value for ROOT, the value as defined in the GDM
                configuration will be be used.
              </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=&lt;etc&gt;/gdm/Init</synopsis>
              <para>
                Directory containing the display init scripts. See the
                ``The Script Directories'' section for more info.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DisplayLastLogin</term>
            <listitem>
              <synopsis>DisplayLastLogin=true</synopsis>
              <para>
                If true then the last login information is printed to the user
                before being prompted for password.  While this gives away some
                info on what users are on a system, it on the other hand should
                give the user an idea of when they logged in and if it doesn't
                seem kosher to them, they can just abort the login and contact
                the sysadmin (avoids running malicious startup scripts).
                This was added in version 2.5.90.0.
              </para>
              <para>
                This is for making GDM conformant to CSC-STD-002-85, although
                that is purely theoretical now.  Someone should read that spec
                and ensure that this actually conforms (in addition to other
                places in GDM).  See
                <filename>http://www.radium.ncsc.mil/tpep/library/rainbow/CSC-STD-002-85.html</filename>
                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>DynamicXServers</term>
            <listitem>
              <synopsis>DynamicXServers=false</synopsis>
              <para>
                If true, the GDM daemon will honor requests to manage
                displays via the <filename>/tmp/.gdm_socket</filename>
                socket connection. Displays can be created, started,
                and deleted with the appropriate commands. The
                <filename>gdmdynamic</filename> command is a convenient
                method to send these messages.
              </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 X 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 displays.  These are
                displays that can be run using the
                <filename>/tmp/.gdm_socket</filename> socket connection.
                This is used for both full flexible displays and for Xnest
                displays.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>FlexiReapDelayMinutes</term>
            <listitem>
              <synopsis>FlexiReapDelayMinutes=5</synopsis>
              <para>
                After how many minutes of inactivity at the login screen
                should a flexi display be reaped.  This is only in effect before
                a user logs in.  Also it does not affect the Xnest
                flexiservers.  To turn off this behavior set this value to 0.
                This was added in version 2.5.90.0.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Greeter</term>
            <listitem>
              <synopsis>Greeter=&lt;bin&gt;/gdmlogin</synopsis>
              <para>
                Full path and name of the greeter executable followed by
                optional arguments.  This is the greeter used for all displays
                except for the XDMCP remote displays.  See also
                <filename>RemoteGreeter</filename>
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Group</term>
            <listitem>
              <synopsis>Group=gdm</synopsis>
              <para>
                The group name under which <command>gdmlogin</command>,
                <command>gdmgreeter</command>,
                <command>gdmchooser</command> 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
                <command>gdmgreeter</command> or <command>gdmlogin</command>
                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=&lt;sbin&gt;/shutdown -h now</synopsis>
              <para>
                Full path and arguments to command to be executed when user
                selects &quot;Shut Down&quot; from the Actions menu.  This can
                be a ';' separated list of commands to try.  If a value is
                missing, the shut down command is not available.  Note that the
                default for this value is not empty, so to disable
                &quot;Shut Down&quot; it must be
                set 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=&lt;var&gt;/log/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=&lt;var&gt;/run/gdm.pid</synopsis>
              <para>
                Name of the file containing the <filename>gdm</filename>
                process id.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>PreFetchProgram</term>
            <listitem>
              <synopsis>PreFetchProgram=command</synopsis>
              <para>
                Program to be run by the GDM greeter/login program when the
                initial screen is displayed.  The  purpose is to provide a hook
                where files which will be used after login can be preloaded to
                speed performance for the user.  The program will be called
                once only, the first time a greeter is displayed.  The
                gdmprefetch command may be used.  This utility will load any
                libraries passed in on the command line, or if the argument
                starts with a &quot;@&quot; character, it will process the file assuming
                it is an ASCII file containing a list of libraries, one per
                line, and load each library in the file.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>PostLoginScriptDir</term>
            <listitem>
              <synopsis>PostLoginScriptDir=&lt;etc&gt;/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=&lt;etc&gt;/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=&lt;etc&gt;/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=&lt;sbin&gt;/shutdown -r now</synopsis>
              <para>
                Full path and optional arguments to the command to be
                executed when user selects Restart from the Actions menu.  This
                can be a ';' separated list of commands to try.  If missing,
                the restart command is not available.  Note that the default 
                for this value is not empty so to disable restart you must set
                this explicitly to an empty value.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>RemoteGreeter</term>
            <listitem>
              <synopsis>RemoteGreeter=&lt;bin&gt;/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 Themed Greeter for your main
                greeter.  See also the <filename>Greeter</filename> key.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>RootPath</term>
            <listitem>
              <synopsis>RootPath=defaultpath (value set by configure)</synopsis>
              <para>
                Specifies the path which will be set in the root's
                session and the {Init,PostLogin,PreSession,PostSession} scripts
                executed by GDM.  This value will be overridden with the value
                from <filename>/etc/default/login</filename> if it
                contains &quot;SUROOT=&lt;pathname&gt;&quot;.  If the
                <filename>/etc/default/login</filename> file exists, but
                contains no value for SUROOT, the value as defined in the GDM
                configuration will be used.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>ServAuthDir</term>
            <listitem>
              <synopsis>ServAuthDir=&lt;var&gt;/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 computer.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>SessionDesktopDir</term>
            <listitem>
              <synopsis>SessionDesktopDir=&lt;etc&gt;/X11/sessions/:&lt;etc&gt;/dm/Sessions/:&lt;share&gt;/xsessions/</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>SoundProgram</term>
            <listitem>
              <synopsis>SoundProgram=<filename>&lt;bin&gt;/play</filename> (or <filename>&lt;bin&gt;/audioplay</filename> on Solaris)</synopsis>
              <para>
                Application to use when playing a sound.  Currently used for
                playing the login sound, see the
                <filename>SoundOnLoginFile</filename> key.  Supported since
                2.5.90.0.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>StandardXServer</term>
            <listitem>
              <synopsis>StandardXServer=/dir/to/X (value assigned by configuration file)</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.   If the user does not enter a username but just
                hits the ENTER key while the login program is requesting the
                username, then GDM will assume the user wants to login
                immediately as the timed user.  Note that no password will be
                asked for this user so you should be careful, although if using
                PAM it can be configured to require password entry before
                allowing login.
              </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
                &quot;root&quot; 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
                application are supported.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>TimedLoginDelay</term>
            <listitem>
              <synopsis>TimedLoginDelay=30</synopsis>
              <para>
                Delay in seconds 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 <command>gdmlogin</command>,
                <command>gdmgreeter</command>,
                <command>gdmchooser</command> 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
                privileges to this directory, and this directory should really
                be sticky and all that, just like the <filename>/tmp</filename>
                directory.
              </para>

              <para>
                Normally if this is the user's home directory GDM will still
                refuse to put cookies there if it thinks it is NFS (by testing
                root-squashing).  This can be changed by setting
                <filename>NeverPlaceCookiesOnNFS</filename> in the
                <filename>[security]</filename> section to false.
              </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 and FreeBSD 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=&lt;etc&gt;/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 X server keeps crashing.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Xnest</term>
            <listitem>
              <synopsis>Xnest=&lt;bin&gt;/X11/Xnest (/usr/openwin/bin/Xnest on Solaris)</synopsis>
              <para>
                The full path and arguments to the Xnest command.  This is used
                for the flexible Xnest displays.  This way the user can start
                new login screens in a nested window.  Of course you must have
                the Xnest display 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=false</synopsis>
              <para>
                Allow root (privileged user) to log in remotely through GDM.
                This value should be set to true to allow 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
                since you can use PAM to do the same thing, and do even
                more.
              </para>
              <para>
                This value will be overridden and set to false if the
                <filename>/etc/default/login</filename> file exists and
                contains &quot;CONSOLE=/dev/login&quot;, and set to true if the
                <filename>/etc/default/login</filename> file exists and
                contains any other value or no value for CONSOLE.
              </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
                &quot;TimedLogin&quot; 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>CheckDirOwner</term>
            <listitem>
              <synopsis>CheckDirOwner=true</synopsis>
              <para>
                By default GDM checks the ownership of the home directories
                before writing to them, this prevents security issues in case
                of bad setup.  However in some instances home directories will
                be owned by a different user and in this case it is necessary
                to turn this option on.  You will also most likely have to
                turn the <filename>RelaxPermissions</filename> key to at least
                value 1 since in such a scenario home directories are likely
                to be group writable.  Supported since 2.6.0.4.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SupportAutomount</term>
            <listitem>
              <synopsis>SupportAutomount=false</synopsis>
              <para>
                By default GDM checks the ownership of the home directories
                before writing to them, this prevents security issues in case
                of bad setup.  However, when home directories are managed by
                automounter, they are often not mounted before they are 
                accessed. This option works around subtleties of Linux
                automounter.
              </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>NeverPlaceCookiesOnNFS</term>
            <listitem>
              <synopsis>NeverPlaceCookiesOnNFS=true</synopsis>
              <para>
                Normally if this is true (which is by default), GDM will not
                place cookies into the user's home directory if this directory
                is on NFS.  Well, GDM will consider any filesystem with
                root-squashing an NFS filesystem.  Sometimes however the remote
                file system can have root squashing and be safe (perhaps by
                using encryption).  In this case set this to 'false'.  Note
                that this option appeared in version 2.4.4.4 and is ignored in
                previous versions.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>PasswordRequired</term>
            <listitem>
              <synopsis>PasswordRequired=false</synopsis>
              <para>
                If true, this will cause PAM_DISALLOW_NULL_AUTHTOK to be
                passed as a flag to pam_authenticate and pam_acct_mgmt,
                disallowing NULL password.  This setting will only take
                effect if PAM is being used by GDM.  This value will be
                overridden with the value from
                <filename>/etc/default/login</filename> if it contains
                &quot;PASSREQ=[YES|NO]&quot;.  If the
                <filename>/etc/default/login</filename> file exists, but
                contains no value for PASSREQ, the value as defined in the GDM
                configuration will be used.
              </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=1</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 computer.  If
                you want to provide display services to computers 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 computer 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>&lt;etc&gt;/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>EnableProxy</term>
            <listitem>
              <synopsis>EnableProxy=false</synopsis>
              <para>
                Setting this to true enables support for running XDMCP sessions
                on a local proxy X server. This may improve the performance of
                XDMCP sessions, especially on high latency networks, as many
                X protocol operations can be completed without going over the
                network.
              </para>
              <para>
                Note, however, that this mode will significantly increase the
                burden on the machine hosting the XDMCP sessions
              </para>
              <para>
                See the <filename>FlexiProxy</filename> and
                <filename>FlexiProxyDisconnect</filename> options for further
                 details on how to configure support for this feature.
              </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 are 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
                than 15 or so seconds would really mean that the terminal was
                turned off or restarted and you would want to end the session.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>ProxyReconnect</term>
            <listitem>
              <synopsis>FlexiProxyReconnect=</synopsis>
              <para>
                Setting this option enables experimental support for session
                migration with XDMCP sessions. This enables users to disconnect
                from their session and later reconnect to that same session,
                possibly from a different terminal.
              </para>
              <para>
                In order to use this feature, you must have a nested X server
                available which supports disconnecting from its parent X server
                and reconnecting to another X server. Currently, the Distributed
                Multihead X (DMX) server supports this feature to some extent
                and other projects like NoMachine NX are busy implementing it.
              </para>
              <para>
                This option should be set to the path of a command which will
                handle reconnecting the XDMCP proxy to another backend display.
                A sample implementation for use with DMX is supplied.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>ProxyXServer</term>
            <listitem>
              <synopsis>ProxyXServer=</synopsis>
              <para>
                The X server command line for a XDMCP proxy. Any nested X server
                like Xnest, Xephr or Xdmx should work fairly well.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Willing</term>
            <listitem>
              <synopsis>Willing=&lt;etc&gt;/gdm/Xwilling</synopsis>
              <para>
                When the machine 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 machine with QUERY
                packets.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

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

        <variablelist>
          <title>[gui]</title>

          <varlistentry>
            <term>AllowGtkThemeChange</term>
            <listitem>
              <synopsis>AllowGtkThemeChange=true</synopsis>
              <para>
                If to allow changing the GTK+ (widget) theme from the greeter.
                Currently this only affects the standard greeter as the
                graphical greeter does not yet have this ability.
                The theme will stay in effect on this display until changed
                and will affect all the other windows that are put up by GDM.
                Supported since 2.5.90.2.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>GtkRC</term>
            <listitem>
              <synopsis>GtkRC=</synopsis>
              <para>
                Path to a <filename>gtkrc</filename> to read when GDM puts up
                a window.  You should really now use the
                <filename>GtkTheme</filename> key for just setting a theme.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GtkTheme</term>
            <listitem>
              <synopsis>GtkTheme=Default</synopsis>
              <para>
                A name of an installed theme to use by default.  It will be
                used in the greeter, chooser and all other GUI windows put up
                by GDM.  Supported since 2.5.90.2.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GtkThemesToAllow</term>
            <listitem>
              <synopsis>GtkThemesToAllow=all</synopsis>
              <para>
                Comma separated list of themes to allow.  These must be the
                names of the themes installed in the standard locations for
                GTK+ themes.  You can also specify 'all' to allow all installed
                themes.  This is related to the
                <filename>AllowGtkThemeChange</filename> key.  Supported since
                2.5.90.2.
              </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=#76848F</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 GTK+ Greeter.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>BackgroundProgramInitialDelay</term>
            <listitem>
              <synopsis>BackgroundProgramInitialDelay=30</synopsis>
              <para>
                The background application will be started after at least that
                many seconds of inactivity.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>RestartBackgroundProgram</term>
            <listitem>
              <synopsis>RestartBackgroundProgram=true</synopsis>
              <para>
                If set the background application will be restarted when it has
                exited, after the delay described below has elapsed.  This
                option can be useful when you wish to run a screen saver 
                application when no user is using the computer.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>BackgroundProgramRestartDelay</term>
            <listitem>
              <synopsis>BackgroundProgramRestartDelay=30</synopsis>
              <para>
                The background application will be restarted after at least that 
                many seconds of inactivity.
              </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 GTK+
                Greeter.
              </para>
            </listitem>
          </varlistentry>        

          <varlistentry>
            <term>BackgroundProgram</term>
            <listitem>
              <synopsis>BackgroundProgram=&lt;bin&gt;/xeyes</synopsis>
              <para>
                If set this command will be run in the background while
                the login window is being displayed.  Note that not all
                applications 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 GTK+ 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 GTK+ 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 GTK+ 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 color,
                2 is color and 3 is image.  This only affects the GTK+ 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 GTK+ Greeter'' section for more information on the
                face browser.  This option only works for the GTK+ Greeter.
                For the Themed 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 X server with a chooser.  XDMCP does not
                need to be enabled on the local computer for this to work.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>ConfigAvailable</term>
            <listitem>
              <synopsis>ConfigAvailable=false</synopsis>
              <para>
                If true, allows the configurator to be run from the greeter.
                Note that the user will need to type in the root password
                before the configurator will be started.  This is set to 
                false by default for additional security.  See the
                <filename>Configurator</filename> option in the daemon
                section.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>DefaultFace</term>
            <listitem>
              <synopsis>DefaultFace=&lt;share&gt;/pixmaps/nophoto.png</synopsis>
              <para>
                If a user has no defined face image, GDM will use the
                &quot;stock_person&quot; icon defined in the current GTK+
                theme.  If no such image is defined, the image specified by 
                <filename>DefaultFace</filename> will be used.  The image must
                be in a gdk-pixbuf supported format and the file must be
                readable to the GDM user.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Include</term>
            <listitem>
              <synopsis>Include=</synopsis>
              <para>
                Comma separated list of users to be included in the face
                browser and in the <command>gdmsetup</command> selection list
                for Automatic/Timed login. 
                See also <filename>Exclude</filename>,
                <filename>IncludeAll</filename>, and
                <filename>MinimalUID</filename>.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Exclude</term>
            <listitem>
              <synopsis>Exclude=bin,daemon,adm,lp,sync,shutdown,halt,mail,...</synopsis>
              <para>
                Comma separated list of users to be excluded from the face
                browser and from the <command>gdmsetup</command> selection list
                for Automatic/Timed login.  Excluded users will still be able to
                log in, but will have to type their username.
                See also <filename>Include</filename>,
                <filename>IncludeAll</filename>, and
                <filename>MinimalUID</filename>.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>IncludeAll</term>
            <listitem>
              <synopsis>IncludeAll=false</synopsis>
              <para>
                By default, an empty include list means display no users.
                By setting IncludeAll to true, the password file will be
                scanned and all users will be displayed aside from users
                excluded via the Exclude setting and user ID's less than
                MinimalUID.  Scanning the password file can be slow on
                systems with large numbers of users and this feature should
                not be used in such environments.
                See also <filename>Include</filename>,
                <filename>Exclude</filename>, and
                <filename>MinimalUID</filename>.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>GlobalFaceDir</term>
            <listitem>
              <synopsis>GlobalFaceDir=&lt;share&gt;/pixmaps/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 Themed Greeter should use.  it
                should refer to a directory in the theme directory set by
                <filename>GraphicalThemeDir</filename>.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GraphicalThemes</term>
            <listitem>
              <synopsis>GraphicalThemes=circles</synopsis>
              <para>
                The graphical themes that the Themed Greeter should use is the
                Mode is set on Random Themes.  This is a &quot;/:&quot;
                delimited list.  It should refer to a directory in the theme
                directory set by <filename>GraphicalThemeDir</filename>.  This
                is only used if <filename>GraphicalThemeRand</filename> is set
                to true.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GraphicalThemeRand</term>
            <listitem>
              <synopsis>GraphicalThemeRand=false</synopsis>
              <para>
                Whether the graphical greeter will use Only One Theme or Random
                Theme mode.  Only One Theme mode uses themes listed by
                <filename>GraphicalTheme</filename>, Random Themes mode uses
                themes listed by <filename>GraphicalThemes</filename>.  A value
                of false sets greeter to use Only One Theme mode, a value of
                true sets the greeter to use Random Theme mode.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GraphicalThemeDir</term>
            <listitem>
              <synopsis>GraphicalThemeDir=&lt;share&gt;/gdm/themes/</synopsis>
              <para>
                The directory where themes for the Themed Greeter are
                installed.
              </para>
            </listitem>
          </varlistentry>

         <varlistentry>
            <term>GraphicalThemedColor</term>
            <listitem>
              <synopsis>GraphicalThemedColor=#76848F</synopsis>
              <para>
                Use this color in the background of the Themed Greeter.  
                This only affects the Themed Greeter.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>InfoMsgFile</term>
            <listitem>
              <synopsis>InfoMsgFile=/path/to/infofile</synopsis>
              <para>
                If present and /path/to/infofile specifies an existing and
                readable text file (e.g. &lt;etc&gt;/infomsg.txt) the contents
                of the file will be displayed in a modal dialog box before the
                user is allowed to login.  This works both with the standard
                and the themable greeters.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>InfoMsgFont</term>
            <listitem>
              <synopsis>InfoMsgFont=fontspec</synopsis>
              <para>
                If present and InfoMsgFile (see above) is used, this specifies
                the font to use when displaying the contents of the InfoMsgFile
                text file.  For example fontspec could be Sans 24 to get a
                sans serif font of size 24 points.
                This works both with the standard and the themable greeters.
              </para>
            </listitem>
          </varlistentry>
          
          
          <varlistentry>
            <term>LocaleFile</term>
            <listitem>
              <synopsis>LocaleFile=&lt;etc&gt;/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 GTK+
                Greeter cannot be changed even if the title bar is turned on.
              </para>
            </listitem>
          </varlistentry>        
          
          <varlistentry>
            <term>Logo</term>
            <listitem>
              <synopsis>Logo=&lt;share&gt;/pixmaps/gnome-logo-large.png</synopsis>
              <para>
                Image file to display in the logo box. The file must be
                in a 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 GTK+ Greeter.
              </para>
            </listitem>
          </varlistentry>

         <varlistentry>
            <term>ChooserButtonLogo</term>
            <listitem>
              <synopsis>ChooserButtonLogo=&lt;share&gt;/pixmaps/gnome-logo-large.png</synopsis>
              <para>
                Image file to display in the file chooser button in
                <command>gdmsetup</command>.  This key is modified by
                <command>gdmsetup</command> and should not be manually
                modified by the user.  This only affects the Login Window
                Preferences (<command>gdmsetup</command>).
              </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>Include</filename>,
                <filename>Exclude</filename>, and
                <filename>IncludeAll</filename>.
              </para>
            </listitem>
          </varlistentry>

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

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

          <varlistentry>
            <term>DefaultRemoteWelcome</term>
            <listitem>
              <synopsis>DefaultRemoteWelcome=true</synopsis>
              <para>
                If set to true, the value &quot;Welcome to %n&quot; is used for
                the <filename>RemoteWelcome</filename>.  This value is
                translated into the appropriate language for the user.  If set
                to false, the <filename>RemoteWelcome</filename> setting is
                used.  This string can use the same special character sequences
                as explained in the &quot;Text Node&quot; section of the
                &quot;Themed Greeter&quot; chapter.  This explains the meaning
                of &quot;%n&quot;.
              </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.
                This string can use the same special character sequences as
                explained in the &quot;Text Node&quot; section of the
                &quot;Themed Greeter&quot; chapter.
                chapter.
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>SetPosition</term>
            <listitem>
              <synopsis>SetPosition=true</synopsis>
              <para>
                If true the position of the login window of the GTK+ 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 th
                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>SoundOnLogin</term>
            <listitem>
              <synopsis>SoundOnLogin=true</synopsis>
              <para>
                If true, the greeter will play a sound or beep when it is
                ready for a login.  See also the
                <filename>SoundOnLoginFile</filename> key.
                Supported since 2.5.90.0.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SoundOnLoginSuccess</term>
            <listitem>
              <synopsis>SoundOnLoginSuccess=true</synopsis>
              <para>
                If true, the greeter will play a sound after a successful login
                attempt.  See also the
                <filename>SoundOnLoginSuccessFile</filename> key.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SoundOnLoginFailure</term>
            <listitem>
              <synopsis>SoundOnLoginFailure=true</synopsis>
              <para>
                If true, the greeter will play a sound after a failed login
                attempt.  See also the
                <filename>SoundOnLoginFailureFile</filename> key.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SoundOnLoginFile</term>
            <listitem>
              <synopsis>SoundOnLoginFile=/path/to/sound.wav</synopsis>
              <para>
                The file that will be played using the specified sound
                application (by default that is
                <filename>/usr/bin/play</filename>) instead of a beep when the
                greeter is ready for a login.  See also the
                <filename>SoundOnLogin</filename> key and the
                <filename>SoundProgram</filename> key.  Supported since
                2.5.90.0.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SoundOnLoginSuccessFile</term>
            <listitem>
              <synopsis>SoundOnLoginSuccessFile=/path/to/sound.wav</synopsis>
              <para>
                The file that will be played using the specified sound
                application (by default that is
                <filename>/usr/bin/play</filename>) after a successful login
                attempt.  See also the <filename>SoundOnLoginSuccess</filename>
                key and the <filename>SoundProgram</filename> key.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SoundOnLoginFailureFile</term>
            <listitem>
              <synopsis>SoundOnLoginFailureFile=/path/to/sound.wav</synopsis>
              <para>
                The file that will be played using the specified sound
                application (by default that is
                <filename>/usr/bin/play</filename>) after a failed login 
                attempt.  See also the <filename>SoundOnLoginFailure</filename>
                key and the <filename>SoundProgram</filename> key.
              </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, Restart,
                Configure, XDMCP chooser and such.  All of those can however
                be turned off individually.  Shutdown, Restart 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 privileges.
              </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 GTK+ Greeter.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Use24Clock</term>
            <listitem>
              <synopsis>Use24Clock=auto</synopsis>
              <para>
                Select the use of 24 hour clock.  Some locales do not
                support 12 hour format (like Finnish, that is
                <filename>fi_FI</filename>), and in those locales this
                setting has no effect at all.
              </para>
              <para>
                Possible values are &quot;auto&quot; (default),
                &quot;true&quot;, and &quot;false&quot;. If this is set to
                &quot;auto&quot; or left empty, then time format is chosen from
                locale settings. Locale settings are based on the language in
                use, thus it is changed by setting environment variables
                LANGUAGE (GNU extension), LANG, LC_MESSAGES or LC_ALL in the
                GDM's runtime environment. Priorities between the mentioned
                environment variables can be found from your system's
                C library manual.
              </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>UseInvisibleInEntry</term>
            <listitem>
              <synopsis>UseInvisibleInEntry=false</synopsis>
              <para>
                Do not show any visual feedback is the password entry.
                This is the standard in console and xdm. Settings this
                option discards the <filename>UseCirclesInEntry</filename>
                option.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DefaultWelcome</term>
            <listitem>
              <synopsis>DefaultWelcome=true</synopsis>
              <para>
                If set to true, the value &quot;Welcome&quot; is used for the
                <filename>Welcome</filename>.  This value is translated
                into the appropriate language for the user.  If set to
                false, the <filename>Welcome</filename> setting is used.
              </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 Themed 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>Multicast</term>
            <listitem>
              <synopsis>Multicast=true</synopsis>
              <para>
                If true and IPv6 is enabled, the chooser will send a multicast
                query to the local network and collect responses from the hosts
                who have joined multicast group. If you don't want to send a
                multicast, you can specify IPv6 address in the <filename>Hosts
                </filename> key. The host will respond if it is listening to
                XDMCP requests and IPv6 is enabled there.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>MulticastAddr</term>
            <listitem>
              <synopsis>MulticastAddr=ff02::1</synopsis>
              <para>
                This is the Link-local Multicast address and is hardcoded here.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>DefaultHostImage</term>
            <listitem>
              <synopsis>DefaultHostImage=&lt;share&gt;/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 a gdk-pixbuf supported format and it must be
                readable for the GDM user.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>HostImageDir</term>
            <listitem>
              <synopsis>HostImageDir=&lt;share&gt;/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="debugsection">
        <title>Debug Configuration</title>

        <variablelist>
          <title>[debug]</title>

          <varlistentry>
            <term>Enable</term>
            <listitem>
              <synopsis>Enable=false</synopsis>
              <para>
                Setting to true sends debug ouput to the syslog.  This can be 
                useful for tracking down problems with GDM.  This output 
                tends to be verbose so should not be turned on for general
                use.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Gestures</term>
            <listitem>
              <synopsis>Gestures=false</synopsis>
              <para>
                Setting to true sends debug ouput concerning the accessibility
                gesture listeners to the syslog.  This can be useful for
                tracking down problems with them not working properly.  This
                output tends to be verbose so should not be turned on for
                general use.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="customcmdsection">
        <title>Custom Commands</title>
        
        <para>
          You can create up to 10 different commands. Gaps between command
          numbers are allowed and their relative positioning within the
          section and with respect to each other is not important as long as
          they conform to the permitted range of [0-9].
          
        </para>
          
        <variablelist>
          <title>[customcommand]</title>
          
          <varlistentry>
            <term>CustomCommand[0-9]</term>
            <listitem>
              <synopsis>CustomCommand[0-9]=</synopsis>
              <para>
                Full path and arguments to command to be executed when user
                selects <filename>n-th</filename> &quot;Custom Command&quot;
                from the Actions menu.  This can be a ';' separated list of
                commands to try.  If the value is empty or missing, then the
                custom command is not available.  By default this value is not
                enabled, so to enable &quot;Custom Command&quot; it must be
                set to a nonempty value.  [0-9] represents the
                <filename>CustomCommand</filename> suffix and can be an
                integer between 0 and 9. 
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandIsPersistent[0-9]</term>
            <listitem>
              <synopsis>CustomCommandIsPersistent[0-9]=</synopsis>
              <para>
                Specifies if <filename>n-th</filename> &quot;Custom
                Command&quot; will appear outside the login manager, for
                example on the desktop through the Log Out/Shut Down dialogs.
                If not specified the default value is &quot;false&quot;. This
                option is only valid if corresponding
                <filename>CustomCommand</filename> is defined. [0-9] represents
                <filename>CustomCommand</filename> suffix and can be an integer
                between 0 and 9.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandLabel[0-9]</term>
            <listitem>
              <synopsis>CustomCommandLabel[0-9]=</synopsis>
              <para>
                Specifies the stock label that will be displayed on the
                <filename>n-th</filename> &quot;Custom Command&quot;
                buttons and menu items. If not specified the default value is
                &quot;Custom_[0-9]&quot;. This option is only valid if
                corresponding <filename>CustomCommand</filename> is defined. 
                [0-9] represents <filename>CustomCommand</filename> suffix
                and can be an integer between 0 and 9. This option can't contain
                any semicolon characters (i.e. &quot;;&quot;).
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandLRLabel[0-9]</term>
            <listitem>
              <synopsis>CustomCommandLRLabel[0-9]=</synopsis>
              <para>
                Specifies the stock label that will be displayed on the
                <filename>n-th</filename> &quot;Custom Command&quot;
                list items and radio buttons.  If not specified the default
                value is  &quot;Execute custom command _[0-9]&quot;. This 
                option is only valid if corresponding
                <filename>CustomCommand</filename> is defined.  [0-9]
                represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandNoRestart[0-9]</term>
            <listitem>
              <synopsis>CustomCommandNoRestart[0-9]=</synopsis>
              <para>
                Specifies if gdm will be stopped/restarted once
                <filename>n-th</filename> &quot;Custom Command&quot;
                has been executed. If not specified the default value is
                &quot;false&quot;. This option is only valid if corresponding
                <filename>CustomCommand</filename> is defined.  [0-9]
                represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9. In addition when
                corresponding <filename>CustomCommandIsPersistent</filename> 
                is set to true,  setting CustomCommandNoRestart to false will
                place corresponding <filename>CustomCommand</filename> in the 
                Shut Down dialog set of actions, setting it to true will place
                corresponding 
                <filename>CustomCommand</filename> in the Log Out dialog set of
                actions.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandText[0-9]</term>
            <listitem>
              <synopsis>CustomCommandText[0-9]=</synopsis>
              <para>
                Specifies the message that will be displayed on the warning
                dialog box once <filename>n-th</filename>
                &quot;Custom Command&quot; button/menu item/radio button/list
                item has been activated.  If not specified the default value is
                &quot;Are you sure?&quot;. This option is only valid if
                corresponding <filename>CustomCommand</filename> is defined.
                [0-9] represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandTooltip[0-9]</term>
            <listitem>
              <synopsis>CustomCommandTooltip[0-9]=</synopsis>
              <para>
                Specifies the message that will be displayed on tooltips for
                <filename>n-th</filename> &quot;Custom Command&quot;
                entries. If not specified the default value is  &quot;Execute
                custom command [0-9]&quot;. This option is only valid if
                corresponding <filename>CustomCommand</filename> is defined.
                [0-9] represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9.
              </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.  The GUI configuration program allows
          users to edit the servers defined in the GDM configuration files
          but currently does not allow adding or deleting entries.  Like
          normal configuration options, <filename>server-</filename>
          sections in the <filename>&lt;etc&gt;/gdm/custom.conf</filename>
          file override values in the
          <filename>&lt;share&gt;/gdm/defaults.conf</filename> file.  In other
          words, if a <filename>server-Standard</filename> section is defined
          in <filename>&lt;etc&gt;/gdm/custom.conf</filename>, then that
          will be used and the section in the
          <filename>&lt;share&gt;/gdm/defaults.conf</filename> file will be
          ignored.
        </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=/path/to/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.
                This is because 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 Display Configuration</title>

        <para>
          The static display configuration specifies what displays should be
          always managed by GDM.  GDM will restart the X server on the display
          if it dies, for example.  There may be as many static displays that
          are managed as you wish, although typically each display is 
          associated with a real display.  For example, if a machine has two
          displays (say display &quot;:0&quot; and display &quot;:1&quot;),
          then this section can be used to specify that a separate login
          screen be managed for each screen.  Each key in the
          <filename>[servers]</filename> section corresponds to the display
          number to be managed.  Normally there is only one key, which is the
          key <filename>0</filename>, which corresponds to the display
          <filename>:0</filename>.
        </para>

        <para>
          The GUI configuration program allows users to edit the static
          display configuration defined in the GDM configuration files 
          and allows the user to add or delete entries.  Like normal
          configuration options, the <filename>[servers]</filename>
          section in the <filename>&lt;etc&gt;/gdm/custom.conf</filename>
          file overrides values in the
          <filename>&lt;share&gt;/gdm/defaults.conf</filename> file.
        </para>

        <variablelist>
          <title>[servers]</title>
          
          <varlistentry>
            <term>&lt;display number&gt;</term>
            <listitem>
              <synopsis>0=Standard</synopsis>
              <para>
                Control section for local displays. 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.
                The gdm daemon doesn't enforce the numbers to be in order or
                for them to be &quot;packed&quot;.  They keyword
                &quot;inactive&quot; can be used instead of a command to
                specify that the display should be not managed.  This can be
                used in the
                <filename>&lt;etc&gt;/gdm/custom.conf</filename> to turn
                off a display that is defined in the
                <filename>&lt;share&gt;/gdm/defaults.conf</filename> file.
              </para>
              
              <para>
                GDM will splice &quot;<filename>-auth
                &lt;ServAuthDir&gt;/:n.Xauth :n</filename>&quot;, where n is
                the display number.  Inside the command line before all
                other arguments before running the X 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 &quot;vt7&quot; to the command line,
                for example, to run on virtual console 7.  However on Linux and
                FreeBSD this is normally done automatically if the
                <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 X servers when the
                <filename>DisallowTCP</filename> option is set.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>priority</term>
            <listitem>
              <synopsis>priority=0</synopsis>
              <para>
                Indicates that the X server should be started at a
                different process priority.  Values can be any integer
                value accepted by the setpriority C library function
                (normally between -20 and 20) with 0 being the default.
                For highly interactive applications, -5 yields good
                responsiveness.  The default value is 0 and the 
                setpriority function is not called if the value is 0.
              </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.  GDM is picky about the file ownership and permissions of 
        the user files it will access, and will ignore files if they are not
        owned by the user or files that have group/world write permission.
        It will also ignore the user if the user's $HOME directory is not
        owned by the user or if the user's $HOME directory has group/world
        write permission.  files must also be smaller than the
        <filename>UserMaxFile</filename> value as defined in the GDM
        configuration.  If it seems that GDM is not properly accessing 
        user configuration settings, the problem is most likely 
        caused by one of these checks failing.
      </para>

      <para>
        First 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> which has two keys:
        <filename>Session</filename> and <filename>Language</filename>.
      </para>

      <para>
        The <filename>Session</filename> key specifies the basename of the
        session <filename>.desktop</filename> file that the user wishes to
        normally use (without the <filename>.desktop</filename> extension, in
        other words).  The <filename>Language</filename> key specifies the
        language that the user wishes to use by default.  If either of these
        keys is missing, the system default is used.  The file would normally
        look as follows:
      </para>

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

      <para>
        Normally GDM will write this file when the user logs in for the first
        time, and rewrite it if the user chooses to change their default values
        on a subsequent login. 
      </para>

      <para>
        If the GDM Face Browser is turned, then the file
        <filename>$HOME/.face</filename> is accessed.  This file should be a 
        standard image that GTK+ can read, such as PNG or JPEG.  It also must
        be smaller than the <filename>MaxIconWidth</filename> and 
        <filename>MaxIconHeight</filename> values defined in the GDM
        configuration or it will be ignored.  Users can run the
        <command>gdmphotosetup</command> program to specify a face image
        and it will copy the file to the <filename>$HOME/.face</filename>
        location and scale it so its longest dimension is not larger than the 
        <filename>MaxIconWidth</filename> or <filename>MaxIconHeight</filename>
        values.  <command>gdmphotosetup</command> takes care to not change
        the aspect ratio of the image.
      </para>

      <para>
        Face images can also be placed in the global face directory, which is
        specified by the <filename>GlobalFaceDir</filename> configuration 
        option ( normally <filename>&lt;share&gt;/pixmaps/faces/</filename>)
        and the filename should be the name of the user, optionally with a
        <filename>.png</filename>, <filename>.jpg</filename>, etc. 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 <command>gdm-stop</command> command which is in the
        <filename>&lt;sbin&gt;/</filename> directory.  To restart GDM, you can
        either send the HUP signal to the main daemon or run the
        <command>gdm-restart</command> command which is also in the
        <filename>&lt;sbin&gt;/</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
        <command>gdm-safe-restart</command> command which is in the
        <filename>&lt;sbin&gt;/</filename> directory as well.
      </para>

      <para>
        The <command>gdmflexiserver</command> command can be used to start
        new flexible (on demand) displays if your system supports virtual
        terminals.  This command will normally lock the current session with a
        screensaver so that the user can safely walk away from the computer and
        let someone else log in.  If more that two flexible displays have 
        started <command>gdmflexiserver</command> will display a pop-up dialog
        allowing the user to select which session to continue.  The user will
        normally have to enter a password to return to the session.  On session
        exit the system will return to the previous virtual terminal.  Run
        <command>gdmflexiserver --help</command> to get a listing of possible
        options.  
      </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>&lt;var&gt;/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 computer, or restart all X servers next time it has
        a chance (which would be useful from an X configuration application).
      </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>

    <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 displays 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.  The <command>gdmflexiserver</command> command uses this
        protocol, for example, to launch flexible (on-demand) displays.
      </para>

      <para>
        gdmflexiserver accepts the following commands with the --command
        option:
      </para>

<screen>
ADD_DYNAMIC_DISPLAY
ALL_SERVERS
ATTACHED_SERVERS
AUTH_LOCAL
CLOSE
FLEXI_XNEST
FLEXI_XNEST_USER
FLEXI_XSERVER
FLEXI_XSERVER_USER
GET_CONFIG
GET_CONFIG_FILE
GET_CUSTOM_CONFIG_FILE
GET_SERVER_LIST
GET_SERVER_DETAILS
GREETERPIDS
QUERY_LOGOUT_ACTION
QUERY_VT
RELEASE_DYNAMIC_DISPLAYS
REMOVE_DYNAMIC_DISPLAY
SERVER_BUSY
SET_LOGOUT_ACTION
SET_SAFE_LOGOUT_ACTION
SET_VT
UPDATE_CONFIG
VERSION
</screen>

      <para>
       These are described in detail below, including required arguments,
       response format, and return codes.
      </para>

      <sect3 id="adddynamic">
      <title>ADD_DYNAMIC_DISPLAY</title>
<screen>
ADD_DYNAMIC_DISPLAY: Create a new server definition that will
                     run on the specified display leaving, it
                     in DISPLAY_CONFIG state.
Supported since: 2.8.0.0
Arguments: &lt;display to run on&gt;=&lt;server&gt;
  Where &lt;server&gt; is either a configuration named in the
  GDM configuration or a literal command name.
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     2 = Existing display
     3 = No server string
     4 = Display startup failure
     100 = Not authenticated
     200 = Dynamic Displays not allowed
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="allservers">
      <title>ALL_SERVERS</title>
<screen>
ALL_SERVERS: List all displays, including console, remote, xnest.
             This can, for example, be useful to figure out if
             the display you are on is managed by the gdm daemon,
             by seeing if it is in the list.  It is also somewhat
             like the 'w' command but for graphical sessions.
Supported since: 2.4.2.96
Arguments: None
Answers:
  OK &lt;server&gt;;&lt;server&gt;;...

  &lt;server&gt; is &lt;display&gt;,&lt;logged in user&gt;

  &lt;logged in user&gt; can be empty in case no one logged in yet

  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="attachedservers">
      <title>ATTACHED_SERVERS</title>
<screen>
ATTACHED_SERVERS: List all attached displays.  Doesn't list XDMCP
                  and xnest non-attached displays.
Note:             This command used to be named CONSOLE_SERVERS,
                  which is still recognized for backwards
                  compatibility. The optional pattern argument
                  is supported as of version 2.8.0.0.
Supported since: 2.2.4.0
Arguments: &lt;pattern&gt; (optional)
  With no argument, all attached displays are returned. The optional
  &lt;pattern&gt; is a string that may contain glob characters '*', '?', and
  '[]'. Only displays that match the pattern will be returned.
Answers:
  OK &lt;server&gt;;&lt;server&gt;;...

  &lt;server&gt; is &lt;display&gt;,&lt;logged in user&gt;,&lt;vt or xnest display&gt;

  &lt;logged in user&gt; can be empty in case no one logged
  in yet, and &lt;vt&gt; can be -1 if it's not known or not
  supported (on non-Linux for example).  If the display is an
  xnest display and is a console one (that is, it is an xnest
  inside another console display) it is listed and instead of
  vt, it lists the parent display in standard form.

  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
     
      <sect3 id="authlocal">
      <title>AUTH_LOCAL</title>
<screen>
AUTH_LOCAL: Setup this connection as authenticated for
            FLEXI_SERVER.  Because all full blown (non-Xnest)
            displays can be started only from users logged in
            locally, and here GDM assumes only users logged
            in from GDM.  They must pass the xauth
            MIT-MAGIC-COOKIE-1 that they were passed before
            the connection is authenticated.
Note:       The AUTH LOCAL command requires the
            --authenticate option, although only
            FLEXI XSERVER uses this currently.
Note:       Since 2.6.0.6 you can also use a global
            &lt;ServAuthDir&gt;/.cookie, which works for all
            authentication except for SET_LOGOUT_ACTION and
            QUERY_LOGOUT_ACTION and SET_SAFE_LOGOUT_ACTION
            which require a logged in display.
Supported since: 2.2.4.0
Arguments: &lt;xauth cookie&gt;
  &lt;xauth cookie&gt; is in hex form with no 0x prefix
Answers:
  OK
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="close">
      <title>CLOSE</title>
<screen>
CLOSE: Close sockets connection
Supported since: 2.2.4.0
Arguments: None
Answers: None
</screen>
      </sect3>

      <sect3 id="flexixnest">
      <title>FLEXI_XNEST</title>
<screen>
FLEXI_XNEXT: Start a new flexible Xnest display.
Note:        Supported on older version from 2.2.4.0, later
             2.2.4.2, but since 2.3.90.4 you must supply 4
             arguments or ERROR 100 will be returned.  This
             will start Xnest using the XAUTHORITY file
             supplied and as the uid same as the owner of
             that file (and same as you supply).  You must
             also supply the cookie as the third argument
             for this display, to prove that you indeed are
             this user.  Also this file must be readable
             ONLY by this user, that is have a mode of 0600.
             If this all is not met, ERROR 100 is returned.
Note:        The cookie should be the MIT-MAGIC-COOKIE-1,
             the first one GDM can find in the XAUTHORITY
             file for this display.  If that's not what you
             use you should generate one first.  The cookie
             should be in hex form.
Supported since: 2.3.90.4
Arguments: &lt;display to run on&gt; &lt;uid of requesting user&gt;
           &lt;xauth cookie for the display&gt; &lt;xauth file&gt;
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = No more flexi servers
     2 = Startup errors
     3 = X failed
     4 = X too busy
     5 = Xnest can't connect
     6 = No server binary
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="flexixnestuser">
      <title>FLEXI_XNEST_USER</title>
<screen>
FLEXI_XNEST_USER: Start a new flexible Xnest display and
                  initialize the greeter with the given username.
Note:             This is a variant of the FLEXI_XNEST command.
Note:             The cookie should be the MIT-MAGIC-COOKIE-1,
                  the first one GDM can find in the XAUTHORITY
                  file for this display.  If that's not what you
                  use you should generate one first.  The cookie
                  should be in hex form.
Supported since:  2.17.7
Arguments: &lt;username&gt; &lt;display to run on&gt; &lt;uid of requesting user&gt;
           &lt;xauth cookie for the display&gt; &lt;xauth file&gt;
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = No more flexi servers
     2 = Startup errors
     3 = X failed
     4 = X too busy
     5 = Xnest can't connect
     6 = No server binary
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="flexixserver">
      <title>FLEXI_XSERVER</title>
<screen>
FLEXI_XSERVER: Start a new X flexible display.  Only supported on
               connection that passed AUTH_LOCAL
Supported since: 2.2.4.0
Arguments: &lt;xserver type&gt;
  If no arguments, starts the standard X server
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = No more flexi servers
     2 = Startup errors
     3 = X failed
     4 = X too busy
     6 = No server binary
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="flexixserveruser">
      <title>FLEXI_XSERVER_USER</title>
<screen>
FLEXI_XSERVER_USER: Start a new X flexible display and initialize the
                    greeter with the given username.  Only supported on
                    connection that passed AUTH_LOCAL
Supported since:    2.17.7 
Arguments: &lt;username&gt; &lt;xserver type&gt;
  If no server type specified, starts the standard X server
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = No more flexi servers
     2 = Startup errors
     3 = X failed
     4 = X too busy
     6 = No server binary
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="getconfig">
      <title>GET_CONFIG</title> 
<screen>
GET_CONFIG:  Get configuration value for key.  Useful so
             that other applications can request configuration
             information from GDM.  Any key defined as GDM_KEY_*
             in gdm.h is supported.  Starting with version 2.13.0.2
             translated keys (such as &quot;greeter/GdmWelcome[cs]&quot; are
             supported via GET_CONFIG.  Also starting with version
             2.13.0.2 it is no longer necessary to include the
             default value (i.e. you can use key &quot;greeter/IncludeAll&quot;
             instead of having to use &quot;greeter/IncludeAll=false&quot;.  
Supported since: 2.6.0.9
Arguments: &lt;key&gt;
Answers:
  OK &lt;value&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     50 = Unsupported key
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="getconfigfile">
      <title>GET_CONFIG_FILE</title> 
<screen>
GET_CONFIG_FILE:  Get config file location being used by
                  the daemon.  If the GDM daemon was started
                  with the --config option, it will return
                  the value passed in via the argument.
Supported since: 2.8.0.2
Arguments: None
Answers:
  OK &lt;full path to GDM configuration file&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="getcustomconfigfile">
      <title>GET_CUSTOM_CONFIG_FILE</title> 
<screen>
GET_CUSTOM_CONFIG_FILE:  Get custom config file location being
                        used by the daemon.
Supported since: 2.14.0.0
Arguments: None
Answers:
  OK &lt;full path to GDM custom configuration file&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = File not found
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="getserverdetails">
      <title>GET_SERVER_DETAILS</title>
<screen>
GET_SERVER_DETAILS:  Get detail information for a specific server.
Supported since: 2.13.0.4
Arguments: &lt;server&gt; &lt;key&gt;
  Key values include:
    NAME      - Returns the server name
    COMMAND   - Returns the server command
    FLEXIBLE  - Returns &quot;true&quot; if flexible, &quot;false&quot;
                otherwise
    CHOOSABLE - Returns &quot;true&quot; if choosable, &quot;false&quot;
                otherwise
    HANDLED   - Returns &quot;true&quot; if handled, &quot;false&quot;
                otherwise
    CHOOSER   - Returns &quot;true&quot; if chooser, &quot;false&quot;
                otherwise
    PRIORITY  - Returns process priority
Answers:
  OK &lt;value&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = Server not found
     2 = Key not valid
     50 = Unsupported key
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="getserverlist">
      <title>GET_SERVER_LIST</title>
<screen>
GET_SERVER_LIST:  Get a list of the server sections from
                  the configuration file.
Supported since: 2.13.0.4
Arguments: None
Answers:
  OK &lt;value&gt;;&lt;value&gt;;...
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = No servers found
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="greeterpids">
      <title>GREETERPIDS</title>
<screen>
GREETERPIDS: List all greeter pids so that one can send HUP
             to them for config rereading.  Of course one
             must be root to do that.
Supported since: 2.3.90.2
Arguments: None
Answers:
  OK &lt;pid&gt;;&lt;pid&gt;;...
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="querylogoutaction">
      <title>QUERY_LOGOUT_ACTION</title>
<screen>
QUERY_LOGOUT_ACTION: Query which logout actions are possible
                     Only supported on connections that passed
                     AUTH_LOCAL.
Supported since: 2.5.90.0
Answers:
  OK &lt;action&gt;;&lt;action&gt;;...
     Where action is one of HALT, REBOOT, SUSPEND or CUSTOM_CMD[0-9].
     An empty list can also be returned if no action is possible.
     A '!' is appended to an action if it was already set with
     SET_LOGOUT_ACTION or SET_SAFE_LOGOUT_ACTION.  Note that
     SET_LOGOUT_ACTION has precedence over
     SET_SAFE_LOGOUT_ACTION.
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="querycustomcmdlabels">
        <title>QUERY_CUSTOM_CMD_LABELS</title>
<screen>
 QUERY_CUSTOM_CMD_LABELS: Query labels belonging to exported custom
                          commands Only supported on connections that
                          passed AUTH_LOCAL.
 Supported since: 2.5.90.0
 Answers:
   OK &lt;label1&gt;;&lt;label2&gt;;...
      Where labelX is one of the labels belonging to CUSTOM_CMDX
      (where X in [0,GDM_CUSTOM_COMMAND_MAX)).  An empty list can
      also be returned if none of the custom commands are exported
      outside login manager (no CustomCommandIsPersistent options
      are set to true).  
   ERROR &lt;err number&gt; &lt;english error description&gt;
      0 = Not implemented
      100 = Not authenticated
      200 = Too many messages
      999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="querycustomcmdnorestartstatus">
        <title>QUERY_CUSTOM_CMD_NO_RESTART_STATUS</title>
<screen>
QUERY_CUSTOM_CMD_NO_RESTART_STATUS: Query NoRestart config options
                                    for each of custom commands Only
                                    supported on connections that
                                    passed AUTH_LOCAL.
Supported since: 2.5.90.0
Answers:
  OK &lt;status&gt;
     Where each bit of the status represents NoRestart value for
     each of the custom commands.
     bit on (1):  NoRestart = true, 
     bit off (0): NoRestart = false.
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="queryvt">
      <title>QUERY_VT</title>
<screen>
QUERY_VT:  Ask the daemon about which VT we are currently on.
           This is useful for logins which don't own
           /dev/console but are still console logins.  Only
           supported on Linux currently, other places will
           just get ERROR 8.  This is also the way to query
           if VT support is available in the daemon in the
           first place.  Only supported on connections that
           passed AUTH_LOCAL.
Supported since: 2.5.90.0
Arguments: None
Answers:
  OK &lt;vt number&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     8 = Virtual terminals not supported
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="releasedynamic">
      <title>RELEASE_DYNAMIC_DISPLAYS</title>
<screen>
RELEASE_DYNAMIC_DISPLAYS: Release dynamic displays currently in 
                          DISPLAY_CONFIG state
Supported since: 2.8.0.0
Arguments: &lt;display to release&gt;
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = Bad display number
     100 = Not authenticated
     200 = Dynamic Displays not allowed
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="removedynamic">
      <title>REMOVE_DYNAMIC_DISPLAY</title>
<screen>
REMOVE_DYNAMIC_DISPLAY: Remove a dynamic display, killing the server
                        and purging the display configuration
Supported since: 2.8.0.0
Arguments: &lt;display to remove&gt;
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     1 = Bad display number
     100 = Not authenticated
     200 = Dynamic Displays not allowed
     999 = Unknown error
</screen>
      </sect3>

      <sect3 id="serverbusy">
      <title>SERVER_BUSY</title>
<screen>
SERVER_BUSY:  Returns true if half or more of the daemon's sockets
              are busy, false otherwise.  Used by slave programs
              which want to ensure they do not overwhelm the 
              sever.
Supported since: 2.13.0.8
Arguments: None
Answers:
  OK &lt;value&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="setlogoutaction">
      <title>SET_LOGOUT_ACTION</title>
<screen>
SET_LOGOUT_ACTION: Tell the daemon to halt/restart/suspend after
                   slave process exits.  Only supported on
                   connections that passed AUTH_LOCAL.
Supported since: 2.5.90.0
Arguments: &lt;action&gt;
  NONE               Set exit action to 'none'
  HALT               Set exit action to 'halt'
  REBOOT             Set exit action to 'reboot'
  SUSPEND            Set exit action to 'suspend'
  CUSTOM_CMD[0-9]    Set exit action to 'custom command [0-9]'
Answers:
  OK
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     7 = Unknown logout action, or not available
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="setsafelogoutaction">
      <title>SET_SAFE_LOGOUT_ACTION</title>
<screen>
SET_SAFE_LOGOUT_ACTION:  Tell the daemon to halt/restart/suspend
                         after everybody logs out.  If only one
                         person logs out, then this is obviously
                         the same as the SET_LOGOUT_ACTION.  Note
                         that SET_LOGOUT_ACTION has precedence
                         over SET_SAFE_LOGOUT_ACTION if it is set
                         to something other then NONE.  If no one
                         is logged in, then the action takes effect
                         effect immediately.  Only supported on
                         connections that passed AUTH_LOCAL.
Supported since: 2.5.90.0
Arguments: &lt;action&gt;
  NONE               Set exit action to 'none'
  HALT               Set exit action to 'halt'
  REBOOT             Set exit action to 'reboot'
  SUSPEND            Set exit action to 'suspend'
  CUSTOM_CMD[0-9]    Set exit action to 'custom command [0-9]'
Answers:
  OK
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     7 = Unknown logout action, or not available
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="setvt">
      <title>SET_VT</title>
<screen>
SET_VT:  Change to the specified virtual terminal.
         This is useful for logins which don't own /dev/console
         but are still console logins.  Only supported on Linux
         currently, other places will just get ERROR 8.
         Only supported on connections that passed AUTH_LOCAL.
Supported since: 2.5.90.0
Arguments: &lt;vt&gt;
Answers:
  OK
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     8 = Virtual terminals not supported
     9 = Invalid virtual terminal number
     100 = Not authenticated
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="updateconfig">
      <title>UPDATE_CONFIG</title> 
<screen>
UPDATE_CONFIG: Tell the daemon to re-read a key from the 
               GDM configuration file.   Any user can request
               that values are re-read but the daemon will
               only do so if the file has been modified
               since GDM first read the file.  Only users
               who can change the GDM configuration file
               (normally writable only by the root user) can
               actually modify the GDM configuration.  This
               command is useful to cause the GDM to update
               itself to recognize a change made to the GDM
               configuration file by the root user.

               Starting with version 2.13.0.0, all GDM keys are
               supported except for the following:

                      daemon/PidFile
                      daemon/ConsoleNotify
                      daemon/User
                      daemon/Group
                      daemon/LogDir
                      daemon/ServAuthDir
                      daemon/UserAuthDir
                      daemon/UserAuthFile
                      daemon/UserAuthFBDir

               GDM also supports the following Psuedokeys:

               xdmcp/PARAMETERS (2.3.90.2) updates the following:
                      xdmcp/MaxPending
                      xdmcp/MaxSessions
                      xdmcp/MaxWait
                      xdmcp/DisplaysPerHost
                      xdmcp/HonorIndirect
                      xdmcp/MaxPendingIndirect
                      xdmcp/MaxWaitIndirect
                      xdmcp/PingIntervalSeconds (only affects new connections)

                xservers/PARAMETERS (2.13.0.4) updates the following:
                      all [server-foo] sections.

                Supported keys for previous versions of GDM:

                      security/AllowRoot (2.3.90.2)
                      security/AllowRemoteRoot (2.3.90.2)
                      security/AllowRemoteAutoLogin (2.3.90.2)
                      security/RetryDelay (2.3.90.2)
                      security/DisallowTCP (2.4.2.0)
                      daemon/Greeter (2.3.90.2)
                      daemon/RemoteGreeter (2.3.90.2)
                      xdmcp/Enable (2.3.90.2)
                      xdmcp/Port (2.3.90.2)
                      daemon/TimedLogin (2.3.90.3)
                      daemon/TimedLoginEnable (2.3.90.3)
                      daemon/TimedLoginDelay (2.3.90.3)
                      greeter/SystemMenu (2.3.90.3)
                      greeter/ConfigAvailable (2.3.90.3)
                      greeter/ChooserButton (2.4.2.0)
                      greeter/SoundOnLoginFile (2.5.90.0)
                      daemon/AddGtkModules (2.5.90.0)
                      daemon/GtkModulesList (2.5.90.0)
Supported since: 2.3.90.2
Arguments: &lt;key&gt;
  &lt;key&gt; is just the base part of the key such as
  &quot;security/AllowRemoteRoot&quot;
Answers:
  OK
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     50 = Unsupported key
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
      
      <sect3 id="queryversion">
      <title>VERSION</title>
<screen>
VERSION: Query GDM version
Supported since: 2.2.4.0
Arguments: None
Answers:
  GDM &lt;gdm version&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     200 = Too many messages
     999 = Unknown error
</screen>
      </sect3>
    </sect2>
  </sect1>

  <!-- ============= GDM Commands ============================= -->

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

    <sect2 id="bindir_binaries">
      <title>GDM User Commands</title>

      <para>
        The GDM package provides the following different commands in
        <filename>bindir</filename> intended to be used by the end-user:
      </para>

      <sect3 id="gdmxnestchoosercommandline">
        <title><command>gdmXnestchooser</command> and
               <command>gdmXnest</command> Command Line Options</title>

        <para>
          The <command>gdmXnestchooser</command> command automatically gets
          the correct display number, sets up access, and runs
          <command>Xnest</command> with -indirect localhost.  This way you
          get an XDMCP chooser provided by your computer. You can also supply
          as an argument the hostname whose chooser should be displayed, so
          <command>gdmXnestchooser somehost</command> will run the XDMCP
          chooser from host <command>somehost</command> inside an Xnest
          session.  You can make this command do a direct query instead by
          passing the <command>-d</command> option as well.  In addition to
          the following options, this command also supports standard GNOME
          options.
        </para>

        <variablelist>
        <title><command>gdmXnestchooser</command> Command Line Options</title>

          <varlistentry>
            <term>-x, --xnest=STRING</term>
            <listitem>
              <para>
                Xnest command line, default is &quot;Xnest&quot;
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-o, --xnest-extra-options=OPTIONS</term>
            <listitem>
              <para>
                Extra options for Xnest, default is no options.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-n, --no-query</term>
            <listitem>
              <para>
                Just run Xnest, no query (no chooser)
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-d, --direct</term>
            <listitem>
              <para>
                Do direct query instead of indirect (chooser)
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-B, --broadcast</term>
            <listitem>
              <para>
                Run broadcast instead of indirect (chooser)
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-b, --background</term>
            <listitem>
              <para>
                Run in background
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--no-gdm-check</term>
            <listitem>
              <para>
                Don't check for running GDM
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="gdmflexichoosercommandline">
        <title><command>gdmflexichooser</command> Command Line Options</title>

        <para>
         The <command>gdmflexiserver</command> command provides three 
         features.  It can be used to run flexible (on demand) X displays,
         to run a flexible display via Xnest, and to send commands to the
         GDM daemon process.
        </para>

        <para>
         Starting a flexible X display will normally lock the current session
         with a screensaver and will redisplay the GDM login screen so a second
         user can log in.   This feature is only available on systems that
         support virtual terminals and have them enabled.  This feature is
         useful if you are logged in as user A, and user B wants to log in
         quickly but user A does not wish to log out.  The X server takes
         care of the virtual terminal switching so it works transparently.
         If there is more than one running display defined with flexible=true,
         then the user is shown a dialog that displays the currently running
         sessions.  The user can then pick which session to continue and will
         normally have to enter the password to unlock the screen. 
        </para>

        <para>
         Flexible displays started via Xnest works on systems that do not 
         support virtual terminals.  This option starts a flexible display
         in a window in the current session.  This does not lock the current
         session, so is not as secure as a flexible server started via
         virtual terminals.
        </para>

        <para>
         The <command>gdmflexiserver --command</command> option provides a way
         to send commands to the GDM daemon and can be used to debug problems
         or to change the GDM configuration.
        </para>

        <para>
         In addition to the following options,
         <command>gdmflexiserver</command> also supports standard GNOME
         options.
        </para>

        <variablelist>
        <title><command>gdmflexichooser</command> Command Line Options</title>

          <varlistentry>
            <term>-c, --command=COMMAND</term>
            <listitem>
              <para>
                Send the specified protocol command to GDM
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-n, --xnest</term>
            <listitem>
              <para>
                Start a flexible X display in Xnest mode
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-l, --no-lock</term>
            <listitem>
              <para>
                Do not lock current screen
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-d, --debug</term>
            <listitem>
              <para>
                Turns on debugging output which gets sent to syslog.  Same as
                turning on debug in the configuration file.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-a, --authenticate</term>
            <listitem>
              <para>
                Authenticate before running --command
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-s, --startnew</term>
            <listitem>
              <para>
                Starts a new flexible display without displaying a dialog
                asking the user if they wish to continue any existing
                sessions.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="gdmdynamiccommandline">
        <title><command>gdmdynamic</command> Command Line Options</title>

        <para>
         The <command>gdmdynamic</command> command which creates, runs, and
         removes displays (X servers) on demand.
        </para>

        <para>
        <command>gdmdynamic</command> allows the management of displays in a
        dynamic fashion.  It is typically used in environments where it is not
        possible to list the possible displays in the GDM configuration files.
        The <command>gdmdynamic</command> command can be used to create a new
        display on a particular display number, run all newly created displays,
        or remove a display.  The <command>gdmdynamic</command> command can also
        be used to list all attached displays, or only attached displays that
        match a pattern.
        </para>

        <para>
        This program is designed to manage multiple simultaneous requests and
        works to avoid flooding the daemon with requests.  If the sockets
        connection is busy, it will sleep and retry a certain number of times
        that can be tuned with the -s and -t options.
        </para>

        <variablelist>
          <title><command>gdmdynamic</command> Command Line Options</title>

          <varlistentry>
            <term></term>
            <listitem>
            <para><emphasis>
              One of the following options can be used per instance:
              </emphasis></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-a display=server</term>
            <listitem>
              <para>
              Add a new display configuration, leaving it in the DISPLAY_CONFIG
              state.  For example,
              <command>&quot;-a 2=StandardServerTwo&quot;</command>
              <command>&quot;-a 3=/usr/X11R6/bin/X -dev /dev/fb2&quot;</command>
              </para>
              <para>
              The display will not actually be started until the display is released
              by calling <command>gdmdynamic</command> again with the -r option.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-r</term>
            <listitem>
              <para>
              Release (run) all displays waiting in the DISPLAY_CONFIG state.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-d display</term>
            <listitem>
              <para>
              Delete a display, killing the X server and purging the
              display configuration. For example, &quot;-d 3&quot;.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-l [pattern]</term>
            <listitem>
              <para>
              List displays via the ATTACHED_SERVERS <command>gdmflexiserver</command>
              command. Without a pattern lists all attached displays.  With a pattern
              will match using glob characters '*', '?', and '[]'. For example:
              <command>&quot;-l Standard*&quot;</command>
              <command>&quot;-l *Xorg*&quot;</command>
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term></term>
            <listitem>
            <para><emphasis>
              These options can be added to the above:
              </emphasis></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-v</term>
            <listitem>
              <para>
              Verbose mode. Prinr diagnostic messages about each message sent
              to GDM.
              </para>
            </listitem>
          </varlistentry>
        
          <varlistentry>
            <term>-b</term>
            <listitem>
              <para>
              Background mode. Fork child to do the work and return immediately.
              </para>
            </listitem>
          </varlistentry>
        
          <varlistentry>
            <term>-t RETRY</term>
            <listitem>
              <para>
              If the daemon socket is busy, <command>gdmdynamic</command> will
              retry to open the connection the specified RETRY number of times.
              Default value is 15.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-s SLEEP</term>
            <listitem>
              <para>
              If the daemon socket is busy, <command>gdmdynamic</command> will
              sleep an amount of time between retries.  A random number of 
              seconds 0-5 is added to the SLEEP value to help ensure that
              multiple calls to gdmdynamic do not all try to restart at the
              same time.  A SLEEP value of zero causes the sleep time to be
              1 second.  Default value is 8 seconds.
              </para>
            </listitem>
          </varlistentry>
        
        </variablelist>
      </sect3>

      <sect3 id="gdmphotosetupcommandline">
        <title><command>gdmphotosetup</command> Command Line Options</title>

        <para>
         Allows the user to select an image that will be used as the user's
         photo by GDM's face browser, if enabled by GDM.  The selected file
         is stored as <filename>~/.face</filename>.  This command accepts
         standard GNOME options.
        </para>
      </sect3>

      <sect3 id="gdmthemetestercommandline">
        <title><command>gdmthemetester</command> Command Line Options</title>

        <para>
         <command>gdmthemetester</command> takes two parameters.  The first
         parameter specifies the environment and the second parameter
         specifies the path name or the name of a theme to view.

         This is a tool for viewing a theme outside of GDM.  It is useful for
         testing or viewing themes.  <command>gdmthemetester</command> requires
         that the system support <command>gdmXnest</command>.

         Note that themes can display differently depending on the theme's
         &quot;Show mode&quot;.  <command>gdmthemetester</command> allows
         viewing the themes in different modes via the environment option.
         Valid environment values and their meanings follow:

<screen>
console       - In console mode.
console-timed - In console non-flexi mode.
flexi         - In flexi mode.
xdmcp         - In remote (XDMCP) mode.
remote-flexi  - In remote (XDMCP) &amp; flexi mode.
</screen>
        </para>
      </sect3>
    </sect2>

    <sect2 id="sbindir_binaries">
      <title>GDM Root User Commands</title>

      <para>
        The GDM package provides the following different commands in
        <filename>sbindir</filename> intended to be used by the root user:
      </para>

      <sect3 id="gdmcommandline">
        <title><command>gdm</command> and <command>gdm-binary</command>
               Command Line Options</title>

        <para>
          The <command>gdm</command> command is really just a script which
          runs the <command>gdm-binary</command>, passing along any options.
          Before launching <command>gdm-binary</command>, the gdm wrapper script
          will source the <filename>&lt;etc&gt;/profile</filename> file to set 
          the standard system environment variables.  In order to better support
          internationalization, it will also set the LC_MESSAGES environment
          variable to LANG if neither LC_MESSAGES or LC_ALL are set.  If you
          really need to set some additional environment before launching GDM,
          you can do so in this script.
        </para>

        <variablelist>
          <title><command>gdm</command> and <command>gdm-binary</command>
                 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 also use a single-dash version,
                &quot;-nodaemon&quot; for compatibility with other display
                managers.
              </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>--config=CONFIGFILE</term>
            <listitem>
              <para>
                Specify an alternative configuration file.
              </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>

          <varlistentry>
            <term>--version</term>
            <listitem>
              <para>
                Print the version of the GDM daemon.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--wait-for-go</term>
            <listitem>
              <para>
                If started with this option, gdm will init, but only start the
                first local display and then wait for a GO message in the fifo
                protocol.  No greeter will be shown until the GO message is
                sent.  Also flexiserver requests will be denied and XDMCP will
                not be started until GO is given.  This is useful for
                initialization scripts which wish to start X early, but where
                you don't yet want the user to start logging in.  So the script
                would send the GO to the fifo once it is ready and GDM will
                then continue.  This functionality was added in version
                2.5.90.0.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="gdmsetupcommandline">
        <title><command>gdmsetup</command> Command Line Options</title>

        <para>
         <command>gdmsetup</command> runs a graphical application for modifying
         the GDM configuration file.  Normally on systems that support
         the PAM userhelper, this is setup such that when you run
         <command>gdmsetup</command> as an ordinary user, it will first
         ask you for your root password before starting.  Otherwise, this
         application may only be run as root.  This application supports
         standard GNOME options.
        </para>
      </sect3>

      <sect3 id="gdmrestartcommandline">
        <title><command>gdm-restart</command> Command Line Options</title>

        <para>
          <command>gdm-restart</command> stops and restarts GDM by sending
          the GDM daemon a HUP signal.  This command will immediately terminate
          all sessions and log out users currently logged in with GDM.
        </para>
      </sect3>

      <sect3 id="gdmsaferestartcommandline">
        <title><command>gdm-safe-restart</command> Command Line Options</title>
  
        <para>
          <command>gdm-safe-restart</command> stops and restarts GDM by
          sending the GDM daemon a USR1 signal.  GDM will be restarted as soon
          as all users log out.
        </para>
      </sect3>

      <sect3 id="gdmstopcommandline">
        <title><command>gdm-stop</command> Command Line Options</title>

        <para>
          <command>gdm-stop</command> stops GDM by sending the GDM daemon
          a TERM signal. 
        </para>
      </sect3>
    </sect2>

    <sect2 id="libexecdir_binaries">
      <title>GDM Internal Commands</title>

      <para>
        The GDM package provides the following different commands in
        <filename>libexecdir</filename> intended to be used by the gdm
        daemon process.
      </para>

      <sect3 id="gdmgreeterlogincommandline">
        <title><command>gdmchooser</command> and <command>gdmlogin</command>
               Command Line Options</title>

        <para>
          The <command>gdmgreeter</command> and <command>gdmlogin</command>
          are two different login applications, either can be used by GDM.  
          <command>gdmgreeter</command> is themeable with GDM themes while
          <command>gdmlogin</command> is themable with GTK+ themes.  These
          applications are normally executed by the GDM daemon.  Both commands
          support standard GNOME options. 
        </para>
      </sect3>

      <sect3 id="gdmchoosercommandline">
        <title><command>gdmchooser</command> Command Line Options</title>

        <para>
          The <command>gdmchooser</command> is the XDMCP chooser application.  
          The <command>gdmchooser</command> is normally executed by the GDM
          daemon.  It supports the following options for XDM compatibility.
          This command supports standard GNOME options and is found in
          support standard GNOME options.
        </para>

        <variablelist>
          <title><command>gdmchooser</command> Command Line Options</title>

          <varlistentry>
            <term>--xdmaddress=SOCKET</term>
            <listitem>
             <para>
                 Socket for XDM communication.
             </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--clientaddress=ADDRESS</term>
            <listitem>
             <para>
               Client address to return in response to XDM.  This option is for
               running gdmchooser with XDM, and is not used within GDM.
             </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--connectionType=TYPE</term>
            <listitem>
             <para>
               Connection type to return in response to XDM.  This option is for
               running gdmchooser with XDM, and is not used within GDM.
             </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="gdm-ssh-session">
        <title><command>gdm-ssh-session</command></title>

        <para>
          The <command>gdm-ssh-session</command> is normally executed by the
          GDM daemon when starting a secure remote connection through ssh.
          It does not take any options.
        </para>
      </sect3>
    </sect2>
  </sect1>

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

  <sect1 id="thememanual">
    <title>Themed Greeter</title>

    <para>
      This section describes the creation of themes for the Themed
      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/">
      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>&lt;share&gt;/gdm/themes/&lt;theme_name&gt;</filename>.
        Usually this would be under <filename>/usr/share</filename>.  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 <command>gdmthemetester</command> script.  This script
        assumes that the X server supports Xnest.  This command 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 display, remote-flexi
        is for flexi displays that are 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:
      </para>

<screen>
<command>gdmthemetester xdmcp circles</command>
</screen>

      <para>
        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>&lt;share&gt;/gdm/themes</filename> directory).  And this is
        the tarball you distribute and people can install from the graphical
        configuration application.  You can do this with the commands:
<screen>
cd &lt;share&gt;/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="greetertag">
        <title>greeter tag</title>

          <para>
            The GDM theme format is specified in XML format contained
            within a &lt;greeter&gt; tag.  You may specify a GTK+ theme to
            be used with this theme by using the gtk-theme element in the
            greeter tag as in the following example.
          </para>

<screen>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE greeter SYSTEM "greeter.dtd"&gt;
&lt;greeter gtk-theme="Crux"&gt;
[...]
&lt;/greeter&gt;
</screen>

          <para>
            Contained within the greeter tag can be the nodes described
            in the next sections of this document.  Some of these nodes are
            containers (box nodes, rect item nodes) which can be used to
            organize how to display the nodes that the user sees and interacts
            with (such as button, pixmap and entry item nodes).
          </para>
      </sect3>

      <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=&quot;alignment&quot; min-width=&quot;num&quot;
xpadding=&quot;num&quot; ypadding=&quot;num&quot; spacing=&quot;num&quot;
homogeneous=&quot;bool&quot;&gt;
</screen>
          Where &quot;num&quot; means number and bool means either
          &quot;true&quot; or &quot;false&quot; The alignment value can be
          either &quot;horizontal&quot; or &quot;vertical&quot;.  If you leave
          any property off it will default to zero or &quot;false&quot; in
          case of &quot;homogeneous&quot; and &quot;vertical&quot; for the
          orientation.
        </para>

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

        <para>
          The &quot;min-width&quot; must be specified in pixels.  Obviously
          there is also a corresponding &quot;min-height&quot; property as
          well.
        </para>
      </sect3>

      <sect3 id="fixednodes">
        <title>Fixed Nodes</title>

        <para>
          Fixed is a container that has its children scattered about
          laid out with precise coordinates.  The size of this container
          is the biggest rectangle that contains all the children.  Fixed
          has no extra properties and so you just use:
<screen>
&lt;fixed&gt;
</screen>
          Then you put other items with proper position nodes inside this.
        </para>

        <para>
          The &quot;toplevel&quot; node is really just like a fixed node.
        </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
          &quot;type&quot;:
        </para>

        <variablelist>
          <varlistentry>
            <term>button</term>
            <listitem>
              <para>
                A button field.  This field uses a GTK+ button.  It is also
                possible to make a "rect" item act like a button by setting
                its button element to true.  However it is better to use
                GTK+ buttons in GDM themes since these are accessible to
                users with disabilities.  Also, GTK+ buttons can be
                themed.  This feature is supported in GDM 2.14.6 and later.
              </para>
            </listitem>
          </varlistentry>

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

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

          <varlistentry>
            <term>list</term>
            <listitem>
              <para>
                 A face browser widget.  Only useful if the face browser is
                 enabled via the configuration.
              </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=&quot;label&quot;&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 by default display as lists, but the
          combo=&quot;true&quot; attribute can be used to specify combo box
          style (combo style supported since GDM 2.16.2).  Some predefined
          lists may be included in a theme by using the following id values.
          Customized lists may also be defined, which are explained below.
        </para>

        <variablelist>
          <varlistentry>
            <term>session</term>
            <listitem>
              <para>
                A list of available sessions, which allows the user to pick
                the session to use.  Supported since GDM 2.16.2.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>language</term>
            <listitem>
              <para>
                A list of available languages, which allows the user to pick
                the language to use.  Supported since GDM 2.16.2.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>userlist</term>
            <listitem>
              <para>
                A Face Browser list, so that users can pick their username
                by clicking on this instead of typing.  This obviously exposes
                the usernames to viewers of the login screen, and is not
                recommended for users who feel that this reduces security.
                The face browser does not support combo box style.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>userlist-rect</term>
            <listitem>
              <para>
                This id can be specified for the &lt;rect&gt; object containing
                the userlist and if the userlist is empty then this rectangle
                will not be shown.  This allows the theme to define something
                like an area with a different color and/or alpha to surround
                the userlist, but only if there are users to display.
                Supported since 2.16.2.
              </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 that displays the date and time.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>pam-prompt</term>
            <listitem>
              <para>
                Label that displays the 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 that displayst PAM/GDM error messages.  Such as when user
                can't log in.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>pam-error-logo</term>
            <listitem>
              <para>
                An image that will be displayed only when a pam-error message
                is being displayed.  This is useful for displaying an
                &quot;Attention&quot; icon, for example.  This feature is
                supported in GDM 2.14.6 and later.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>pam-message</term>
            <listitem>
              <para>
                Label that displays the 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 &quot;button&quot; value as follows:
<screen>
&lt;item type=&quot;rect&quot; id=&quot;disconnect_button&quot; button=&quot;true&quot;&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 configuration application.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>custom_cmd_button[0-9]</term>
            <listitem>
              <para>
                Runs the <filename>n-th</filename> custom command.
              </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>
                Restart 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/restart/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 &quot;pos&quot;
          node.  For example:
<screen>
&lt;pos x=&quot;0&quot; y=&quot;4&quot; width=&quot;100%&quot; height=&quot;100%&quot;/&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
          &quot;n&quot; &quot;ne&quot; &quot;e&quot; &quot;se&quot;
          &quot;s&quot; &quot;sw&quot; &quot;w&quot; and &quot;nw&quot; or
          &quot;center&quot; which stand for the different edges/corners or
          &quot;center&quot; for center.  For example:
<screen>
&lt;pos x=&quot;10%&quot; y=&quot;50%&quot; anchor=&quot;w&quot; width=&quot;80%&quot; height=&quot;95&quot;/&gt;
</screen>
        </para>

        <para>
          If the item contains a box, you can specify width and height to be
          &quot;box&quot; 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>
          If the item contains an SVG image, you can specify width and height
          to be &quot;scale&quot; to mean that the SVG image should be scaled
          to fit the requested area.
        </para>

        <para>
          You can also specify an &quot;expand&quot; property to either be
          &quot;true&quot; 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>

        <para>
          There are two extra properties you can specify (as of 2.4.4.3) for
          labels (and labels only).  The first is &quot;max-width&quot; which
          will specify the maximum width of the label in pixels.  And the
          second is &quot;max-screen-percent-width&quot; which specifies the
          maximum percentage of the screen width that the label can occupy.
          By default no label will occupy more then 90% of the screen by width.
          An example may be:
<screen>
&lt;item type=&quot;label&quot;&gt;
&lt;pos x="10%" max-screen-percent-width="50%"/&gt;
</screen>
        </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=&quot;flexi,remote&quot;/&gt;
</screen>
        </para>

        <para>
          You can also specify the &quot;type&quot; 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
          &quot;true&quot; in the GDM configuration.
        </para>
        <para>
          <filename>config</filename>, if ConfigAvailable is set to
          &quot;true&quot; in the GDM configuration.
        </para>
        <para>
          <filename>custom_cmd[0-9]</filename>, if <filename>n-th</filename>
          CustomCommand is specified in the GDM configuration.
        </para>
        <para>
          <filename>halt</filename>, if HaltDaemon is specified in
          the GDM configuration.
        </para>
        <para>
          <filename>reboot</filename>, if RebootCommand is specified in
          the GDM configuration.
        </para>
        <para>
          <filename>suspend</filename>, if SuspendCommand is specified in
          the GDM configuration.
        </para>
        <para>
          <filename>system</filename>, if SystemMenu is specified in
          the GDM configuration.
        </para>
        <para>
          <filename>timed</filename>, if TimedLoginEnabled is set to
          &quot;true&quot; in the GDM configuration.
        </para>

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

        <para>
          Note that if SystemMenu is off then the halt, restart, suspend,
          chooser and config choices will not be shown, 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 (except for userlist - refer to Color node
          below), 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 &quot;rect&quot; (alpha can be omitted and defaults to
            0.0):
<screen>
&lt;normal color=&quot;#ffffff&quot; alpha=&quot;0.0&quot;&gt;
</screen>
        </para>

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

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

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

        <para>
          Note that alternative image file can be specified using the altfile[n]
          property. GDM will use the last valid image filename specified. 
          For example:
<screen>
&lt;normal file=&quot;picture.png&quot; altfile1=&quot;distribution-blah-image.png&quot; altfile2=&quot;distribution-foo-image.png&quot;/&gt;
</screen>
         If <filename>distribution-foo-image.png</filename> is a valid image 
         filename it will be used. Otherwise distribution-blah-image.png will 
         be used if valid.  This feature supported since 2.16.3.
        </para>

      </sect3>

      <sect3 id="listcoloronodes">
        <title>Face Browser Icon/Label Color Nodes</title>

        <para>
          If the item type is of userlist, then the background color for the
          icon and label can be set separately via the the following tag:
        </para>

        <para>
<screen>
&lt;color iconcolor=&quot;#dddddd&quot; labelcolor=&quot;#ffffff&quot;/&gt;
</screen>
        </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 &quot;xml:lang&quot; attribute is
          omitted, the C locale is assumed):
<screen>
&lt;text xml:lang=&quot;fr&quot;&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
          &quot;foo&lt;sup&gt;bar&lt;/sup&gt;&quot;, you must type:
<screen>
&lt;text&gt;&quot;foo&lt;sup&gt;bar&lt;/sup&gt;&quot;&lt;/text&gt;
</screen>
        </para>

        <para>
          Text nodes can contain the following special character sequences
          which will be translated as follows:
        </para>

        <para>
          %% - A literal % character
        </para>
        <para>
          %c - Clock time.  Only labels with the &quot;clock&quot; id will
          update automatically every second.  Other labels will contain a
          static timestamp.
        </para>
        <para>
          %d - Display name (DISPLAY environment variable)
        </para>
        <para>
          %h - Hostname (gethostname output)
        </para>
        <para>
          %m - Machine name (uname.machine output)
        </para>
        <para>
          %n - Node name (uname.nodename output)
        </para>
        <para>
          %o - Domain name (getdomainname output)
        </para>
        <para>
          %r - Release name (uname.release output)
        </para>
        <para>
          %s - System name (uname.sysname output)
        </para>
        <para>
          %t - Current timed delay value from configuration file (0 if off)
          followed by the word &quot;seconds&quot; if value is greater than 1
          or the word &quot;second&quot; if the value is 1.  This character
          sequence is intended to be only used internally to display the
          &quot;timed-label&quot; message, which is automatically updated every
          second.
        </para>
        <para>
          %u - Timed username value from configuration file (empty if off)
          This character sequence is intended to be only used internally to
          display the &quot;timed-label&quot; message, which is automatically
          updated every second.
        </para>
        <para>
          \n - Carriage return
        </para>
        <para>
          _ - An underscore causes the following character to be underlined.
          If it precedes a % character sequence, the string that replaces the
          character sequence is underlined.
        </para>
      </sect3>

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

        <para>
          Certain common localized labels can be specified via the stock
          tags.  The &quot;text&quot; tag is ignored if the &quot;stock&quot;
          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>cancel</filename>, _(&quot;_Cancel&quot;
        </para>
        <para>
          <filename>caps-lock-warning</filename>,
          _(&quot;Caps Lock key is on.&quot; 
        </para>
        <para>
          <filename>chooser</filename>, _(&quot;Remote Login via _XDMCP&quot;
        </para>
        <para>
          <filename>config</filename>, _(&quot;_Configure&quot;
        </para>
        <para>
          <filename>custom_cmd[0-9]</filename>, _(&quot;Custom_[0-9]&quot;
        </para>
        <para>
          <filename>disconnect</filename>, _(&quot;D_isconnect&quot;
        </para>
        <para>
          <filename>halt</filename>, _(&quot;Shut _Down&quot;
        </para>
        <para>
          <filename>language</filename>, _(&quot;_Language&quot;
        </para>
        <para>
          <filename>ok</filename>, _(&quot;_OK&quot;
        </para>
        <para>
          <filename>quit</filename>, _(&quot;_Quit&quot;
        </para>
        <para>
          <filename>reboot</filename>, _(&quot;_Restart&quot;
        </para>
        <para>
          <filename>session</filename>, _(&quot;_Session&quot;
        </para>
        <para>
          <filename>startover</filename>, _(&quot;_Start Over&quot;
        </para>
        <para>
          <filename>suspend</filename>, _(&quot;Sus_pend&quot;
        </para>
        <para>
          <filename>system</filename>, _(&quot;_Actions&quot;
          (Formerly &quot;S_ystem&quot;
        </para>
        <para>
          <filename>timed-label</filename>,
          _(&quot;User %u will login in %t&quot;
        </para>
        <para>
          <filename>username-label</filename>, _(&quot;Username:&quot;
        </para>
        <para>
          <filename>welcome-label</filename>, _(&quot;Welcome to %n&quot;
        </para>

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

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

        <para>
          Currently there is one item which is 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,
          <filename>ServAuthDir</filename> is
          <filename>&lt;var&gt;/lib/gdm</filename> and we have the following in the
          theme:
        </para>

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

        <para>
          Then if the user chooses 'Foo' then 
          <filename>&lt;var&gt;/lib/gdm/:0.GreeterInfo</filename> will contain:
<screen>
custom-config=foo
</screen>
        </para>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="accessibility">
    <title>Accessibility</title>
      <para>
        GDM supports &quot;Accessible Login&quot; to allow users to log in to
        their desktop session even if they cannot easily use the screen, mouse,
        or keyboard in the usual way.  Only the &quot;Standard Greeter&quot;
        supports accessibility, so use this login GUI for accessibility
        support.  This is done by specifying the &quot;Standard Greeter&quot;
        in the &quot;Local&quot; tab for the console display and specifying
        the &quot;Standard Greeter&quot; in the &quot;Remote&quot; tab for 
        remote displays.  Or you can modify the <filename>Greeter</filename>
        configuration option by hand to be <command>gdmlogin</command>.
      </para>

      <para>
        The Standard Greeter supports the ability to launch assistive
        technologies at login time via configurable &quot;gestures&quot; from
        the standard keyboard, pointing device, or switch device attached to
        the USB or PS/2 mouse port.  Also the user can change the visual
        appearance of the login UI before logging in, for instance to use a
        higher-contrast color scheme for better visibility.  
      </para>

       <sect2 id="accessibilityconfig">
          <title>Accessibility Configuration</title>
             <para>
             In order to enable Accessible Login, the system administrator must
             make some changes to the default login configuration by manually
             modifying three human-readable configuration files, stored in
             the GDM configuration, AccessKeyMouseEvents and
             AccessDwellMouseEvents.
             </para>

             <para>
             In order to allow users to change the color and contrast scheme of
             the login dialog, make sure the
             <filename>AllowThemeChange</filename> parameter in the GDM
             configuration is set to &quot;true&quot;.
             </para>

             <para>
             To restrict user changes to the visual appearance to a subset of
             available themes, the <filename>GtkThemesToAllow</filename>
             parameter in the GDM configuration can be set to a list of
             acceptable themes separated by commas.  For example:
             </para>

<screen>
GtkThemesToAllow=HighContrast,HighContrastInverse
</screen>

             <para>
             To enable the use of assistive technologies such as the Onscreen
             Keyboard, Screen Reader, or Magnifier, the
             <filename>AddGtkModules</filename> parameter in the GDM
             configuration must be uncommented and set to &quot;true&quot;.
             Also the <filename>GtkModulesList</filename> parameter must be
             uncommented and set as follows:
             </para>

<screen>
GtkModulesList=gail:atk-bridge:dwellmouselistener:keymouselistener
</screen>

             <para>
             The use of assistive technologies and the atk-bridge module
             requires the registry daemon, <command>at-spi-registryd</command>,
             to be running.  This is handled by the GDM GUI starting with
             version 2.17.
             </para>

             <para>
             System administrators may wish to load only the minimum subset of
             these modules which is required to support their user base.
             Depending on the end-user needs, not all of the above GtkModules
             may need to be loaded.  If your end-users need the integrated
             Screen Reader and Magnifier, you must include &quot;gail&quot; and
             &quot;atk-bridge&quot;.  If your end-users will be using a
             pointing device without buttons or switches, include
             &quot;dwellmouselistener&quot;.  If some of your users will use
             pointing devices with switches, alternative physical keyboards, or
             switch/button devices, include &quot;keymouselistener&quot;.
             Including all four is suitable for most system configurations.
             The Onscreen Keyboard can operate without gail and atk-bridge, but
             with a reduced feature set; for optimum accessibility we recommend
             including both gail and atk-bridge.
             </para>

             <para>
             Once &quot;keymouselistener&quot; and/or
             &quot;dwellmouselistener&quot; have been added to the GtkModules
             loaded by GDM, you can assign end-user actions with the launching
             of specific assistive technologies.  These gesture associations
             are contained in files AccessKeyMouseEvents and
             AccessDwellMouseEvents, respectively.  Both files are located in
             the &lt;etc&gt;/gdm/modules directory.  The gesture format is
             described in the two configuration files.
             </para>

             <para>
             The AccessKeyMouseEvents file controls the keymouselistener
             Gesture Listener and is used to define key-press, mouse button,
             or XInput device sequences that can be used to launch applications
             needed for accessibility.  In order to reduce the likelihood of
             unintentional launch, these &quot;gestures&quot; may be associated
             with multiple switch presses and/or minimum durations.  Note that
             the XKB extension is needed for key gestures to work, so you may
             need to add +xkb to your Xserver command line for gestures to
             work properly.
             </para>

             <para>
             The DwellKeyMouseEvents file controls the dwellmouselistner and
             supports gestures that involve only motion of a pointing device
             such as the system mouse of an alternative pointing device such
             as a head pointer or trackball may also be defined.   All gestures
             are specified by the same syntax; that is, there is no distinction
             between a &quot;core mouse&quot; gesture and motion from an
             alternate input device.
             </para>

             <para>
             Motion gestures are defined as &quot;crossing events&quot; into
             and out of the login dialog window.  If the
             &quot;dwellmouselistener&quot; GtkModule is loaded, alternative
             pointing devices are temporarily &quot;latched&quot; to the core
             pointer, such that motion from alternative devices results in
             movement of the onscreen pointer.
             </para>

             <para>
             In order to use text-to-speech services at login time (for
             instance, when using the Screen Reader in speech mode) on some
             operating systems, the GDM user must be made a member of the
             &quot;audio&quot; group
             </para>

             <para>
             Currently GDM does not remember what accessible technology
             programs have been started when switching applications.  So
             if the user switches between the login program and the 
             chooser, for example, then it is necessary for the user to
             redo the gesture.  Users may need to also set up their default
             session so that the assistive technologies required are
             started automatically (or have appropriate key-bindings 
             defined to start them) after the user session has started.
             </para>

             <para>
             There are some issues that cause users to have problems
             getting the gesture listeners to work.  It is recommended that
             people use GDM version 2.8.0.5 or later for best results.  
             Some X servers have a bug which causes detectable autorepeat
             to fail when XEVIE is enabled (which happens when atk-bridge
             is included as a GTK Module).  This bug causes key gestures
             with a duration greater than 0 to always fail.  A workaround
             is to simply redefine all key gestures so they have zero length
             duration.  Some versions of GOK and gnopernicus will not launch
             unless the &quot;gdm&quot; user has a writable home directory.
             If you see an hourglass cursor when you complete a gesture but the
             program does not start, then you are likely having this problem.
             It should be considered a bug for AT programs to require having a
             writable home directory, so please file a bug with the AT
             program if you encounter this problem.  Also note that some input
             devices require X server configuration before GDM will recognize
             them.
             </para>
       </sect2>
       <sect2 id="accessibilitysound">
          <title>Accessibility Login Sound Configuration</title>
             <para>
             By default, GDM requires a media application such as
             &quot;sox&quot; to be present to play sounds for successful or
             failed login.  GDM defaults
             the location of this application to
             <filename>&lt;bin&gt;/play</filename> (or
             <filename>&lt;bin&gt;/audioplay</filename> on Solaris.  This can
             be changed via the SoundProgram GDM configuration option.  
             Typically most text-to-speech programs (such as ORCA or 
             Gnopernicus) use a separate mechanism to play audio.
             </para>
        </sect2>
  </sect1>

  <sect1 id="solaris">
    <title>Solaris Specific Features</title>

       <sect2 id="solarisconfiguration">
          <title>Solaris Configuration</title>
             <para>
               On Solaris, the following configuration is recommended.
               This turns on IPv6 and also turns on PreFetch for
               performance benefit.

<screen>
./autogen.sh --prefix=/usr --sysconfdir=/etc/X11 --localstatedir=/var
   --libexecdir=/usr/lib --enable-ipv6=yes --with-at-bindir=/usr/sfw/bin
   --with-prefetch --with-post-path=/usr/openwin/bin
</screen>
             </para>

             <para>
               Configuring GDM with the
               &quot;--with-post-path=/usr/openwin/bin&quot; on Solaris is
               recommended for access to programs like Xnest.
             </para>
       </sect2>

       <sect2 id="solarislogindevperm">
          <title>Solaris /etc/logindevperm</title>
             <para>
               GDM supports /etc/logindevperm, but only on Solaris 10 and higher.
               Refer to the logindevperm.4 man page for more information.
             </para>

             <para>
               To make /etc/logindevperm functionality work on Solaris 9 or
               earlier you would have to hack the GDM PreSession and
               PostSession script to chmod the device permissions directly.  In
               other words, if /etc/logindevperm had a listing like this:
             </para>

<screen>
/dev/console    0600    /dev/sound/*            # audio devices
</screen>
     
             <para>
               The PreSession script would need to be modified to chown
               /dev/console to the user:group who is logging into the console
               and ensure whatever permissions is specified in /etc/logindevperm
               (0600 for the line above).  Then in the PostSession script chmod
               the device back to root:root and ensure 0600 this time (do not
               use the value in the /etc/logindevperm file).  Linux uses a
               different mechanism for managing device permissions, so this
               extra scripting is not needed.
             </para>
       </sect2>

       <sect2 id="solarisautomaticlogin">
          <title>Solaris Automatic Login</title>
             <para>
               Automatic login does not work on Solaris because PAM is not
               configured to support this feature by default.  Automatic 
               login is a GDM feature that is not enabled by default, so you
               would only notice this problem if you try to make use of it.
               Turning this feature on causes your computer to login to a
               specified username on startup without asking for username
               and password.  This is an insecure way to set up your
               computer. 
             </para>

             <para>
               If using Solaris 10 or lower, then you need to compile
               the pam_allow.c code provided with the GDM release and
               install it to /usr/lib/security (or provide the full path
               in /etc/pam.conf) and ensure it is owned by uid 0 and not
               group or world writable.
             </para>

             <para>
               The following are reasonable pam.conf values for turning on
               automatic login in GDM.  Make sure to read the PAM documentation
               (e.g. pam.d/pam.conf man page) and be comfortable with the
               security implications of any changes you intend to make to
               your configuration.
             </para>

<screen>
       gdm-autologin auth  required    pam_unix_cred.so.1
       gdm-autologin auth  sufficient  pam_allow.so.1
       gdm-autologin account  sufficient  pam_allow.so.1
       gdm-autologin session  sufficient  pam_allow.so.1
       gdm-autologin password  sufficient  pam_allow.so.1
</screen>

             <para>
               The above setup will cause no lastlog entry to be generated.  If
               a lastlog entry is desired, then use the following for session:
             </para>

<screen>
       gdm-autologin session required pam_unix_session.so.1
</screen>
       </sect2>

       <sect2 id="solarisother">
          <title>Other Solaris Features</title>
             <para>
               GDM supports a few features specific to Solaris, as follows:
             </para>

             <para>
               GDM supports Solaris Auditing if running on Solaris 10 or
               higher.  GDM should not be used if auditing is needed and
               running Solaris 9 or older.
            </para>

            <para>
                GDM supports a security feature which causes the X server to
                run as the user instead of as the root user.  GDM must be using
                PAM for this feature to be enabled, which is the normal case
                for Solaris.  This second feature has the side-effect of
                causing the X server to always restart between sessions, which
                disables the AlwaysRestartServer configuration option.  
            </para>

            <para>
                Solaris supports the <filename>/etc/default/login</filename>
                interface, which affects the <filename>DefaultPath</filename>,
                <filename>RootPath</filename>,
                <filename>PasswordRequired</filename>, and
                <filename>AllowRemoteRoot</filename> options as described in the
                &quot;Configuration&quot; section.
            </para>
       </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 server machine.  So let's call one X terminal
        <filename>xterminal</filename> and let's call the server machine
        <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=/path/to/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 server <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=/path/to/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 will 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 several 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>
    
    <sect2 id="customcommand">
      <title>Defining Custom Commands</title>
      
      <para>
        Suppose you want to add a custom command to the GDM menu that will give
        you the oportunity to boot into other operating system such as Windoze.
        Jsut add the following options into the
        <filename>[customcommand]</filename> section of the GDM configuration
        file.
        
        <screen>
          [customcommand]
          CustomCommand0=/sbin/rebootwindoze;/usr/local/sbin/rebootwindoze
          CustomCommandLabel0=_Windoze
          CustomCommandLRLabel0=Reboot into _Windoze
          CustomCommandText0=Are you sure you want to restart the computer into Windoze?
          CustomCommandTooltip0=Restarts the computer into Windoze
          CustomCommandIsPersistent0=true
        </screen>

        CustomCommand0 specifies two commands separated by a semicolon:
        <filename>/sbin/rebootwindoze</filename> and 
        <filename>/usr/local/sbin/rebootwindoze</filename>.  GDM will use
        the first valid command in the list.  This allows different 
        commands for different operating systems to be included.
      </para>
      <para>
        Note, that besides being able to customise this option to reboot into
        different operating systems you can also use it to define your own
        custom behaviours that you wish to run from the GDM menu.  Suppose you
        want to give users the oportunity to run system update scripts from the
        login screen. Add the following options into the
        <filename>[customcommand]</filename> section of your GDM configuration
        file.
        
        <screen>
          [customcommand]
          CustomCommand0=/sbin/updatesystem;/usr/local/sbin/updatesystem
          CustomCommandLabel0=_Update Me
          CustomCommandLRLabel0=Update the system
          CustomCommandText0=Are you sure you want to update the system software?
          CustomCommandTooltip0=Updates the system
          CustomCommandNoRestart0=true
        </screen>
      </para>
      
      <para>
        Both custom commands could be defined as follows.

        <screen>
          [customcommand]
          CustomCommand0=/sbin/rebootwindoze;/usr/local/sbin/rebootwindoze
          CustomCommandLabel0=_Windoze
          CustomCommandLRLabel0=Reboot into _Windoze
          CustomCommandText0=Are you sure you want to restart the computer into Windoze?
          CustomCommandTooltip0=Restarts the computer into Windoze
          CustomCommandIsPersistent0=true
          
          CustomCommand1=/sbin/updatesystem;/usr/local/sbin/updatesystem
          CustomCommandLabel1=_Update Me
          CustomCommandLRLabel1=Update the system
          CustomCommandText1=Are you sure you want to update the system software?
          CustomCommandTooltip1=Updates the system
          CustomCommandNoRestart1=true
        </screen>
        </para>
      
      <para>
        There can be up to 10 custom commands numbered 0-9.

        <screen>
          [customcommand]
          CustomCommand0=/sbin/rebootwindoze;/usr/local/sbin/rebootwindoze
          CustomCommandLabel0=_Windoze
          CustomCommandLRLabel0=Reboot into _Windoze
          CustomCommandText0=Are you sure you want to restart the computer into Windoze?
          CustomCommandTooltip0=Restarts the computer into Windoze
          CustomCommandIsPersistent0=true
          
          CustomCommand1=/sbin/updatesystem;/usr/local/sbin/updatesystem
          CustomCommandLabel1=_Update Me
          CustomCommandLRLabel1=Update the system
          CustomCommandText1=Are you sure you want to update the system software?
          CustomCommandTooltip1=Updates the system
          CustomCommandNoRestart1=true
          
          CustomCommand3=/sbin/do_something
          .
          .
          .
          
          CustomCommand4=/sbin/do_something_else
          .
          .
          .
        </screen>
      </para>
    </sect2>
  </sect1>

  <sect1 id="troubleshooting">
    <title>Troubleshooting</title>

    <para>
      This section discusses helpful tips for getting GDM working.  In general,
      if you have a problem using GDM, you can submit a bug to the
      &quot;gdm&quot; category in
      <ulink type="http"
       url="http://bugzilla.gnome.org/">bugzilla.gnome.org</ulink>
      or send an email to the
      <address><email>gdm-list@gnome.org</email></address> mail list.
    </para>

    <para>
      If GDM is failing to work properly, it is always a good idea to include
      debug information.  Use the <command>gdmsetup</command> command to turn
      on debug (&quot;Enable debug messages to system log&quot; checkbox in the
      &quot;Security&quot; tab), then use GDM to the point where it fails, and
      include the GDM output sent to your system log
      (<filename>&lt;var&gt;/log/messages</filename> or
      <filename>&lt;var&gt;/adm/messages</filename> depending on your operating
      system).  Since the system log can be large, please only include the GDM
      debug information and do not sent the entire file.  If you do not see any
      GDM syslog output, you may need to configure syslog (see syslog.3c man
      page).
    </para>

    <para>
      You should not leave debug on after collecting data.  It will clutter your
      syslog and slow system performance.
    </para>

    <sect2 id="wontstart">
      <title>GDM Will Not Start</title>

      <para>
         There are a many problems that can cause GDM to fail to start, but
         this section will discuss a few common problems and how to approach
         tracking down a problem with GDM starting.   Some problems will 
         cause GDM to respond with an error message or dialog when it tries
         to start, but it can be difficult to track down problems when GDM
         fails silently.
      </para>

      <para>
         First make sure that the Xserver is configured properly.  The 
         GDM configuration file contains a command in the [server-Standard]
         section that is used for starting the Xserver.  Verify that this
         command works on your system.  Running this command from the 
         console should start the Xserver.  If it fails, then the problem
         is likely with your Xserver configuration.  Refer to your Xserver
         error log for an idea of what the problem may be.  The problem may
         also be that your Xserver requires different command-line options.
         If so, then modify the Xserver command in the GDM configuration file
         so that it is correct for your system.
      </para>

      <para>
         Another common problem is that the GDM greeter program is having
         trouble starting.  This can happen, for example, if GDM cannot find
         a needed library or other resource.  Try starting the Xserver and
         a terminal program, set the shell environment variable 
         DOING_GDM_DEVELOPMENT=1 and run
         <command>&lt;lib&gt;/gdmlogin</command>
         or <command>&lt;lib&gt;/gdmgreeter</command>.  Any error messages
         echoed to the terminal will likely highlight the problem.  Also,
         turning on debug and checking the output sent to the system log 
         will often highlight the problem.
      </para>

      <para>
         Also make sure that the <filename>/tmp</filename> directory has
         reasonable ownership and permissions, and that the machine's file
         system is not full.  These problems will cause GDM to fail to start.
      </para>
    </sect2>

    <sect2 id="notaccessfile">
      <title>GDM Will Not Access User Settings</title>

      <para>
         GDM saves user settings, such as your default session and default
         language, in the <filename>~/.dmrc</filename>.  Other files, such
         as the user's <filename>~/.Xauthority</filename> file will also
         affect login.  GDM, by default, is strict about how it tries to
         access files in the user's home directory, and will ignore the file if
         they do not conform to certain rules.  You can use the 
         <filename>RelaxPermissions</filename> configuration option to
         make GDM less strict about how it accesses files in the user's
         home directory, or correct the permissions issues that cause GDM
         to ignore the file.  This is discussed in detail described in the
         &quot;File Access&quot; section of the &quot;Overview&quot;. 
      </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:
-->