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.13.0.3"> 
    <!ENTITY date "12/12/2005"> 
]>

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

    <abstract role="description">
      <para>
       Reference manual for the Gnome Display Manager (GDM).
      </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>
      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>
      Themed Greeter - The themable login window (
      <command>gdmgreeter</command>).
    </para>

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

    <para>
      Configurator - The configuration application (<command>gdmsetup</command>).
    </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>/usr/share/pixmaps</filename> if GDM was configured
      with <command>--prefix=/usr</command>.  Normally also note that
      GDM is installed with <command>--sysconfigdir=/etc/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>/etc/X11</filename>.
    </para>

  </sect1>

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

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

      <para> 
        GDM is a replacement for XDM, the X Display Manager. Unlike its
        competitors (X3DM, KDM, WDM) GDM was written from scratch and does not
        contain any original XDM / X Consortium code. 
      </para>

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

    </sect2>

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

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

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

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

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

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

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

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

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

    </sect2>

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

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

      <para>
        Next GDM supports flexible or on demand servers which can be started
        via the socket protocol with the <command>gdmflexiserver</command>
        command.  This feature is only available to users logged in on the
        console.  <command>gdmflexiserver</command> can also be used to
        launch nested <command>Xnest</command> servers which can be started
        even if not logged inot the console.  This is done by running
        <command>gdmflexiserver -n</command>.  These servers are not
        restarted when the user session ends.  The
        <command>gdmflexiserver</command> normally locks the current
        session with a screensaver before starting a new server.
      </para>

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

    </sect2>

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

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

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

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

      <para>
        GDM only supports the MIT-MAGIC-COOKIE-1 authentication system.
        Normally little is gained from the other schemes, and no effort has
        been made to implement them so far.  Because of this the cookies go
        over the wire as clear text, and thus you should be careful about what
        network you use this on.  That is, you should be careful about through
        where your XDMCP connection is going.  Note that obviously if snooping
        is possible, then the attacker could just snoop your password as you
        log in, so a better XDMCP authentication wouldn't help you much anyway.
        If snooping is possible and undesirable, then you had better use ssh
        for tunneling an X connection anyway rather then using GDM's 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 anal 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, plus 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>

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

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

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

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

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

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

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

      <para>
        You should use the daemon name <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>

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

    <sect2 id="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 and since 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 small 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 don't have be be
        readable by the GDM 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 "face/picture=" 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 "stock_person"
        icon defined in the current GTK+ theme.  If no such image is defined,
        it will fallback to the iamge specified in the
        <filename>DefaultFace</filename> configuration option, normally
        /usr/share/pixmaps/nobody.png.
      </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>gdm.conf</filename> <filename>Include</filename> 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 these 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.
      </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 don't know who can get to a login screen.  This is especially true
        if you run XDMCP (turned off by default).  However you should never
        run XDMCP on an open network anyway.
      </para>
    </sect2>

    <sect2 id="stdgreeter">
      <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.
      </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 and optionally shutdown/reboot/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="graphgreeter">
      <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.
      </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.
      </para>

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

    </sect2>

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

      <para>
        GDM itself will use syslog to log errors or status.  It can also log
        debugging information, 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 users home directory who would then have to log out and
        log back in to clear this.  This could be especially nasty if quotas
        are set.  GDM also correctly traps the XFSZ signal and stops writing
        the file, which would lead to killed sessions if the file was
        redirected in the old fashioned way from the script.
      </para>

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

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

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

    </sect2>

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

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

      <para>
        The GDM user, and group, which are normally just
        <command>gdm</command> should not be user or group of any particular
        privilege.  The reason for using them is to have the user interface
        run as a user without privileges so that in the unlikely case that
        someone finds a weakness in the GUI, they cannot access root on the
        computer.
      </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 server authorization directory (the
        <filename>ServAuthDir</filename>), which contains all the X server
        authorization files and other private information.  This means that
        someone who gains the GDM user/group 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>.
      </para>

      <para>
        The server authorization directory (the
        <filename>ServAuthDir</filename>) is used for a host of random
        internal data in addition to the X server authorization files, and the
        naming is really a relic of history.  GDM daemon enforces this
        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 server authorization directory and
        treats it in the same way as the temporary directory with respect to
        creating files.  This way someone breaking the GDM user cannot mount
        attacks by creating links in this directory.  Similarly the X server
        log directory is treated safely, but that directory should really be
        owned and writable only by root.
      </para>

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

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

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

    <para>
      The configuration files (especially the <filename>gdm.conf</filename>
      file) contain lots of useful comments and examples, so also read this
      for more information about changing your setup.
    </para>

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

    <para> 
      The <filename>gdm.conf</filename> file contains the main configuration
      choices for GDM.
    </para>

    <para>
      GDM may be configured to support both system-wide configuration if
      built with the <command>--with-configdir</command> option.  This
      allows the gdm.conf file to be installed to a directory that can
      be mounted across multiple-systems.  Regardless of whether this
      option is used, GDM will first look for the gdm.conf file in the
      <filename>&lt;etc&gt;/gdm</filename> directory.  This way 
      machine-specific configuration always overrides the system-wide
      defaults.  The gdm --config option may also be used to specify the 
      configuration file location.  All GDM utilities (such as
      <command>gdmchooser</command>, <command>gdmsetup</command>, etc.)
      query the GDM daemon process and will use the same configuration
      file as being used by the daemon.  The GDM2 daemon must be restarted
      to change the configuration file being used.  GDM 2.8.0.1 and earlier
      only supported machine-specific configuration.
    </para>

    <para> 
      <filename>factory-gdm.conf</filename> is the configuration file as
      shipped with the daemon.  This can be useful if you wish to revert to
      the default configuration.
    </para>

    <para>
      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 can be defined in 
      the <filename>gdm.conf</filename> file, 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>
Init/
PostLogin/
PostSession/
PreSession/
modules/
locale.alias
Xsession
XKeepsCrashing
    </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>
      The <filename>Init</filename>, <filename>PreSession</filename>,
      <filename>PostSession</filename>, and <filename>PostLogin</filename> 
      scripts are described later in this section.
    </para>

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

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

    <para>
      <filename>gdm.conf</filename> configuration settings are used by most
      GDM applications since a number of configuration settings are used by
      each program.
    </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>/usr/share/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>/usr/share/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
        servers.  If none of the above were found, GDM will run
        <filename>Init/Default</filename>. The script will be run as root and
        GDM blocks until it terminates. Use the <filename>Init/*</filename>
        script for applications that are supposed to run alongside with the GDM
        login window. xconsole for instance.  Commands to set the background
        etc. goes in this file too.
      </para>

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

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

      <para>
        After the user session has been setup from the GDM side of things, GDM
        will run the scripts in the <filename>PreSession</filename> directory,
        again in the same manner as the <filename>Init</filename> directory.
        Use this script for local session management or accounting stuff.  The
        <filename>$USER</filename> environment variable contains the login of
        the authenticated user and <filename>$DISPLAY</filename> is set to the
        current display.  The script should return 0 on success.  Any other
        value will cause GDM to terminate the current login process.  This is
        not true for failsafe sessions however.  Also
        <filename>$X_SERVERS</filename> environmental variable is set and this
        points to a fake generated x servers file for use with the sessreg
        accounting 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 users profile and generally do all
        the voodoo that is needed to launch a session.  Since many systems
        reset the language selections done by GDM, GDM will also set the
        <filename>$GDM_LANG</filename> variable to the selected language.  You
        can use this to reset the language environmental variables after you
        run the users profile.  If the user elected to use the system language,
        then <filename>$GDM_LANG</filename> is not set. 
      </para>

      <para> 
        When the user terminates his session, the
        <filename>PostSession</filename> script will be run. Again operation
        is similar to <filename>Init</filename>, <filename>PostLogin</filename>
        and <filename>PreSession</filename>.  Again the script will be run with
        root privileges, the slave daemon will block and the
        <filename>$USER</filename> environment variable will contain the name
        of the user who just logged out and <filename>$DISPLAY</filename> will
        be set to the display the user used, however note that the X server for
        this display may already be dead and so you shouldn't try to access it.
        Also <filename>$X_SERVERS</filename> environmental variable is set and
        this points to a fake generated x servers file for use with the sessreg
        accounting 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 File - <filename>gdm.conf</filename></title>
      
      <para>
        The daemon and the accompanying utilities use a common
        configuration file: <filename>gdm.conf</filename>.  GDM may be
        configured to support both system-wide configuration if
        built with the <command>--with-configdir</command> option.  This
        allows the gdm.conf file to be installed to a directory that can
        be mounted across multiple-systems.  Regardless of whether this
        option is used, GDM will first look for the gdm.conf file in the
        <filename>&lt;etc&gt;/gdm</filename> directory.  This way 
        machine-specific configuration always overrides the system-wide
        defaults.  The gdm --config option may instead be used to specify
        a configuration file installed to another location.  All GDM
        utilities (such as All GDM utilities (such as
        <command>gdmchooser</command>, <command>gdmsetup</command>, etc.)
        query the GDM daemon process and will use the same configuration
        file as being used by the daemon.  The GDM2 daemon must be
        restarted to change the configuration file being used.  GDM 2.8.0.1
        and earlier only supported machine-specific configuration.
      </para>

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

      <para>
        <filename>gdm.conf</filename> follows the standard
        <filename>.ini</filename> style configuration file syntax.  Keywords
        in brackets define sections, strings before an equal sign (=) are
        variables and the data after equal sign represents their value.  Empty
        lines or lines starting with the hash mark (#) are ignored.  The
        graphical configurator will try to preserve both comments (lines with
        a hash mark) and the overall structure of the file so you can intermix
        using the GUI or hand 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 "trusted" modules
                should be used to minimize security issues.
              </para>
              <para>
                Usually this is used for accessibility modules.  The modules
                which are loaded are specified with the
                <filename>GtkModulesList</filename> key.
              </para>
            </listitem>
          </varlistentry>

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

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

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

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

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

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

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

              <para>
                Alternatively, the name may end with a vertical bar |, the
                pipe symbol.  The name is then used as a 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 "login" 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=/bin:/usr/bin:/usr/bin/X11:/usr/local/bin</synopsis>
              <para>
                Specifies the path which will be set in the user's session.
                This value will be overridden with the value from
                /etc/default/login if it contains "ROOT=&lt;pathname&gt;".  If
                the /etc/default/login file exists, but contains no value for
                ROOT, the gdm.conf value will 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 server that will just work.
                This is tried before the <filename>XKeepsCrashing</filename>
                script is run.
              </para>
            </listitem>
          </varlistentry>

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

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

          <varlistentry>
            <term>FlexiReapDelayMinutes</term>
            <listitem>
              <synopsis>FlexiReapDelayMinutes=5</synopsis>
              <para>
                After how many minutes of inactivity at the login screen
                should a flexi server be reaped.  This is only in effect before
                a user logs in.  Also it does not affect the Xnest
                flexiservers.  To turn off this behaviour 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 servers
                except for the XDMCP remote servers.  See also
                <filename>RemoteGreeter</filename>
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Group</term>
            <listitem>
              <synopsis>Group=gdm</synopsis>
              <para>
                The group name under which <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=/sbin/shutdown -h now</synopsis>
              <para>
                Full path and arguments to command to be executed when user
                selects Shutdown from the Actions menu.  This can be a ';'
                separated list of commands to try.  If a value is missing, the
                shutdown command is not available.  Note that the default for
                this value is not empty so to disable shutdown you must set
                this explicitly to an empty value.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>KillInitClients</term>
            <listitem>
              <synopsis>KillInitClients=true</synopsis>
              <para>
                Determines whether GDM should kill X clients started by the
                init scripts when the user logs in.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>LogDir</term>
            <listitem>
              <synopsis>LogDir=&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>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=/sbin/shutdown -r now</synopsis>
              <para>
                Full path and optional arguments to the command to be
                executed when user selects Reboot from the Actions menu.  This
                can be a ';' separated list of commands to try.  If missing,
                the reboot command is not available.  Note that the default for
                this value is not empty so to disable reboot you must set this
                explicitly to an empty value.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>RemoteGreeter</term>
            <listitem>
              <synopsis>RemoteGreeter=&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=/sbin:/usr/sbin:/bin:/usr/bin:/usr/bin/X11:/usr/local/bin</synopsis>
              <para>
                Specifies the path which will be set in the root's
                session and the {Init,PostLogin,PreSession,PostSession} scripts
                executed by GDM.  This value will be overridden with the value
                from /etc/default/login if it contains "SUROOT=&lt;pathname&gt;".
                If the /etc/default/login file exists, but contains no value
                for SUROOT, the gdm.conf value 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;/usr/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=/usr/bin/play</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=/usr/X11R6/bin/X</synopsis>
              <para>
                Full path and arguments to the standard X server command.
                This is used when gdm cannot find any other definition,
                and it's used as the default and failsafe fallback in a
                number of places.  This should be able to run some sort
                of X server.
              </para>
            </listitem>
          </varlistentry>

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

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

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

          <varlistentry>
            <term>TimedLoginDelay</term>
            <listitem>
              <synopsis>TimedLoginDelay=30</synopsis>
              <para>
                This is the delay before the <filename>TimedLogin</filename>
                user will be logged in.  It must be greater then or equal to 10.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>User</term>
            <listitem>
              <synopsis>User=gdm</synopsis>
              <para>
                The username under which <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 users 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 server keeps crashing.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Xnest</term>
            <listitem>
              <synopsis>Xnest=/usr/bin/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 servers.  This way the user can start
                new login screens in a nested window.  Of course you must have
                the Xnest server from your X server packages installed for this
                to work.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        
      </sect3>

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

          <varlistentry>
            <term>AllowRemoteRoot</term>
            <listitem>
              <synopsis>AllowRemoteRoot=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
                /etc/default/login file exists and contains
                "CONSOLE=/dev/login", and set to true if the
                /etc/default/login 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
                "TimedLogin" user by letting the login window time out, just
                like the local user on the first console.
              </para>
              <para>
                Note that this can make a system quite insecure, and thus is
                off by default.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>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>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 users 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 /etc/default/login if it
                contains "PASSREQ=[YES|NO]".  If the /etc/default/login
                file exists, but contains no value for PASSREQ, the
                gdm.conf value 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 server 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 rebooted 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 server sends a WILLING packet back after a QUERY it
                sends a string that gives the current status of this server.
                The default message is the system ID, but it is possible to
                create a script that displays customized message.  If this
                script doesn't exist or this key is empty the default message
                is sent.  If this script succeeds and produces some output,
                the first line of it's output is sent (and only the first
                line).  It runs at most once every 3 seconds to prevent
                possible denial of service by flooding the server with QUERY
                packets.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        
      </sect3>

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

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

          <varlistentry>
            <term>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=/usr/bin/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 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
                "stock_person" 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 an 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 "/:" 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 an gdk-pixbuf supported format and it must be readable by
                the GDM user. If no file is specified the logo feature
                is disabled.
                This only affects the 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 gdmsetup.
                This key is modified by gdmsetup and should not be manually
                modified by the user.
                This only affects the Login Window Preferences (gdmsetup).
              </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 "Welcome to %n" 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.
                false, the <filename>Welcome</filename> setting is used.
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>RunBackgroundProgramAlways</term>
            <listitem>
              <synopsis>RunBackgroundProgramAlways=false</synopsis>
              <para>
                If this is true then the background 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, Reboot,
                Configure, XDMCP chooser and such.  All of those can however
                be turned off individually.  Shutdown, Reboot and Suspend can
                be turned off by just setting the corresponding keys to empty.
                Note that the actions menu is only shown on local logins as it
                would not be safe or even desirable on remote logins, so you
                don't have to worry about remote users having any sort of
                console 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 "auto" (default), "true", and
                "false". If this is set to "auto" 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 "UseCirclesInEntry" option.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DefaultWelcome</term>
            <listitem>
              <synopsis>DefaultWelcome=true</synopsis>
              <para>
                If set to true, the value "Welcome" 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 an 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="serverdefs">

        <title>X Server definitions</title>

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

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

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

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

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

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

      </sect3>

      <sect3 id="localservers">

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

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

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

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

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

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

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

      </sect3>
        
    </sect2>

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

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

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

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

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

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

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

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

      <para>
        To stop GDM, you can either send the TERM signal to the main daemon or
        run the <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) servers 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 servers 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 servers that are
        running and who is logged in on them, and if GDM supports it on your
        operating system, also the virtual terminals of all the console logins.
        You can also request new flexible servers to be run with this protocol,
        such as with the <command>gdmflexiserver</command> command.
      </para>

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

      <screen>
VERSION
AUTH_LOCAL
FLEXI_XSERVER
FLEXI_XNEST
ATTACHED_SERVERS
ALL_SERVERS
GET_SERVER_LIST
GET_SERVER_DETAILS
GET_CONFIG
GET_CONFIG_FILE
UPDATE_CONFIG
GREETERPIDS
QUERY_LOGOUT_ACTION
SET_LOGOUT_ACTION
SET_SAFE_LOGOUT_ACTION
QUERY_VT
SET_VT
CLOSE
      </screen>

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

      <sect3 id="queryversion">
      <title>VERSION</title>
      <screen>
VERSION: Query 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>

      <sect3 id="authlocal">
      <title>AUTH_LOCAL</title>
      <screen>
AUTH_LOCAL: Setup this connection as authenticated for
            FLEXI_SERVER Because all full blown (non-Xnest)
            servers 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.
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="flexixserver">
      <title>FLEXI_XSERVER</title>
      <screen>
FLEXI_XSERVER: Start a new X flexible server
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="flexixnest">
      <title>FLEXI_XNEST</title>
      <screen>
FLEXI_XNEXT: Start a new flexible Xnest server
Note:        Supported an 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="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 gdm.conf 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="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:  None
Answers:
  OK &lt;display&gt;
  ERROR &lt;err number&gt; &lt;english error description&gt;
     0 = Not implemented
     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="attachedservers">
      <title>ATTACHED_SERVERS</title>
      <screen>
ATTACHED_SERVERS: List all attached servers.  Doesn't list XDMCP and xnest
                  non-attached servers
Supported since: 2.2.4.0
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.
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;
     1 = Not implemented
     200 = Too many messages
     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 server 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="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
     50 = Unsupported key
     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.  Key values include:
    NAME      - Returns the server name
    COMMAND   - Returns the server command
    FLEXIBLE  - Returns "true" if flexible, "false" otherwise
    CHOOSABLE - Returns "true" if choosable, "false" otherwise
    HANDLED   - Returns "true" if handled, "false" otherwise
    CHOOSER   - Returns "true" if chooser, "false" otherwise
Supported since: 2.13.0.4
Arguments: &lt;server&gt; &lt;key&gt;
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="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 "greeter/GdmWelcome[cs]" 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 "greeter/IncludeAll"
             instead of having to use "greeter/IncludeAll=false".  
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.
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="updateconfig">
      <title>UPDATE_CONFIG</title> 
      <screen>
UPDATE_CONFIG: Tell the daemon to re-read a key from the 
               gdm.conf 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 the last time it was read.  Only users
               who can change the gdm.conf 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.conf
               file by the root user.

               Starting with version 2.13, 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

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)
  xdmcp/PARAMETERS (2.3.90.2) (pseudokey, all the parameters)
         xdmcp/MaxPending
         xdmcp/MaxSessions
         xdmcp/MaxWait
         xdmcp/DisplaysPerHost
         xdmcp/HonorIndirect
         xdmcp/MaxPendingIndirect
         xdmcp/MaxWaitIndirect
         xdmcp/PingIntervalSeconds (only affects new connections)
  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
  "security/AllowRemoteRoot"
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="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 or SUSPEND.  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="setlogoutaction">
      <title>SET_LOGOUT_ACTION</title>
      <screen>
SET_LOGOUT_ACTION:  Tell the daemon to halt/reboot/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'

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/reboot/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 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'

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="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="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="close">
      <title>CLOSE</title>
      <screen>
CLOSE Answers: None
Supported since: 2.2.4.0
      </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
        EXPANDED_BINDIR 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 "Xnest"
              </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 servers,
         to run a flexible server via Xnest, and to send commands to the
         GDM daemon process.
        </para>

        <para>
         Starting a flexible X servers 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 server 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 servers started via Xnest works on systems that do not 
         support virtual terminals.  This option starts a flexible server
         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 server 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 server 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>
        Some environments need the ability to tell GDM to create and manage new
        displays on the fly, where it is not possible to list the possible
        displays in gdm.conf. 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 gdmdynamic command
        can also be used to list all attached displays, or only attached
        displays that match a pattern.
        </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. For example,
              <command>"-a 2=StandardServerTwo"</command>
              <command>"-a 3=/usr/X11R6/bin/X -dev /dev/fb2"</command>
              </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, "-d 3".
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-l [pattern]</term>
            <listitem>
              <para>
              List displays via the ATTACHED_SERVERS command. Without a pattern
              lists all attached displays. With a pattern will match using glob
              characters '*', '?', and '[]'. For example:
              <command>"-l Standard*"</command>
              <command>"-l *Xorg*"</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>
        </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 ~/.face.  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
         "Show mode".  <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
        EXPANDED_SBINDIR 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 use just a single dash with this
                option to preserve compatibility with XDM.
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>--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, gdm.conf.  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>

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

          <varlistentry>
            <term>--config=CONFIGFILE</term>
            <listitem>
              <para>
                Specify an alternative configuration file.  By default, 
                <command>gdmsetup</command> will edit the same configuration
                file being used by the GDM daemon. 
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </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
        EXPANDED_LIBEXECDIR 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>
    </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 you also have installed the Xnest X server.  It takes two
        arguments, first the environment that should be used.  This is one of
        console, console-timed, flexi, remote-flexi, xdmcp.  Where console is a
        standard console login, console-timed is a console login with a timed
        login going on, flexi is for any local flexible server, remote-flexi is
        for flexi server that is not local (such as an Xnest flexiserver run
        from a remote display) and xdmcp is for remote XDMCP connections.  The
        second argument is the theme name.  So for example to test how things
        look in the XDMCP mode with the circles theme you would run:
      </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>/usr/share/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 /usr/share/gdm/themes
tar czvf &lt;theme_name&gt;.tar.gz &lt;theme_name&gt;/
      </screen>
      </para>

    </sect2>

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

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

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

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

        <para>
          The "min-width" must be specified in pixels.  Obviously there is
          also a corresponding "min-height" 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 "toplevel" 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 "type":
        </para>

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

          <varlistentry>
            <term>config_button</term>
            <listitem>
              <para>
                Runs the GDM configuration application.
              </para>
            </listitem>
          </varlistentry>

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

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

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

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

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

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

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

        </variablelist>
      </sect3>

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

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

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

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

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

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

        <para>
          If the item contains an SVG image, you can specify width and height
          to be "scale" to mean that the SVG image should be scaled to fit
          the requested area.
        </para>

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

        <para>
          There are two extra properties you can specify (as of 2.4.4.3) for
          labels (and labels only).  The first is "max-width" which will
          specify the maximum width of the label in pixels.  And the second is
          "max-screen-percent-width" 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="label"&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="flexi,remote"/&gt;</screen>
        </para>

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

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

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

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

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

        <para>
          Depending on the item type (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 "rect" (alpha can be omitted and defaults to 0.0):
        <screen>&lt;normal color="#ffffff" alpha="0.0"&gt;</screen>
        </para>

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

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

        <para>
          Note that relative pathnames are assumed to be in the same 
          directory as the theme <filename>.xml</filename> file in
          <filename>&lt;share&gt;/gdm/themes/&lt;theme_name&gt;</filename>.
        </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="#dddddd" labelcolor="#ffffff"/&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 "xml:lang" attribute is
          omitted, the C locale is assumed):
        <screen>&lt;text xml:lang="fr"&gt;Option&lt;/text&gt;</screen>
        </para>

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

      </sect3>

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

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

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

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

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

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

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

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

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

  <sect1 id="accessibility">
    <title>Accessibility</title>
       <para>
       GDM supports "Accessible Login" 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.  This feature allows the user to launch
       assistive technologies at login time by means of special "gestures"
       from the standard keyboard and from a keyboard, pointing device, or
       switch device attached to the USB or PS/2 mouse port.   It also
       allows the user to change the visual appearance of the login UI
       before logging in, for instance to use a higher-contrast color
       scheme for better visibility.  GDM only supports accessibility with
       the GTK+ Greeter, so the "Greeter" parameter in gdm.conf must be
       set to the GTK+ Greeter "gdmlogin".
       </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
             gdm.conf, AccessKeyMouseEvents and AccessDwellMouseEvents.
             </para>

             <para>
             In order to allow users to change the color and contrast scheme of
             the login dialog, make sure the "AllowThemeChange" parameter in
             gdm.conf is set to "true".
             </para>

             <para>
             To restrict user changes to the visual appearance to a subset of
             available themes, the "GtkThemesToAllow" parameter in gdm.conf 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 "AddGtkModules"
             parameter in gdm.conf must be uncommented and set to "true".  Also
             the "GtkModulesList" parameter must be uncommented and set as
             follows:
             </para>

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

             <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 "gail" and
             "atk-bridge".  If your end-users will be using a pointing device
             without buttons or switches, include "dwellmouselistener".  If
             some of your users will use pointing devices with switches,
             alternative physical keyboards, or switch/button devices, include
             "keymouselistener".  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 gail and atk-bridge.
             </para>

             <para>
             Once "keymouselistener" and/or "dwellmouselistener" 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.
             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 'gestures' may be associated with
             multiple switch presses and/or minimum durations.
             </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 'core mouse' gesture and motion from an alternate input
             device.
             </para>

             <para>
             Motion gestures are defined as "crossing events" into and out of
             the login dialog window.  If the 'dwellmouselistener' GtkModule
             is loaded, alternative pointing devices are temporarily "latched"
             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
             "audio" group
             </para>

             <para>
             There are some issues that cause some 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 Xservers 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 gdm 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.
             Also note that some input devices require Xserver 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 "sox" to be 
             present to play login sounds.  GDM defaults the location of this
             application to <filename>/usr/bin/play</filename> (or 
             <filename>/usr/bin/audioplay</filename> on Solaris.  This can
             be changed via the SoundProgram configuration option in
             <filename>gdm.conf</filename>.  
             </para>
     </sect2>
  </sect1>

  <sect1 id="solaris">
    <title>Solaris Specific 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.
    </para>

    <para>
        GDM supports a security feature which causes the Xserver 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 Xserver to
        always restart between sessions, which disables the
        AlwaysRestartServer gdm.conf 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
        Configuration section.
    </para>

  </sect1>

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

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

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

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

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

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

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

      <para>
        Suppose you want to make a lab full of X terminals that all connect
        to some choice of servers.  For now let's make it
        <filename>appserverone</filename> and
        <filename>appservertwo</filename>.  Again we'll call our example X
        terminal 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=/usr/X11R6/bin/X
flexible=false
chooser=true
        </screen>
        And again this definition should in fact be included in the standard
        configuration file.  Notice that we made the
        <filename>chooser</filename> key true here.  This will run the XDMCP
        chooser for this server, and when the user chooses a host GDM will run
        a query for that host.  Then we'll define our local servers as follows:
        <screen>
[servers]
0=Chooser
        </screen>
      </para>

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

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

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

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

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