mdm.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
    "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd" [
    <!ENTITY legal SYSTEM "legal.xml">
    <!ENTITY version "2.20.4"> 
    <!ENTITY date    "03/10/2008"> 
    <!ENTITY mdash   "&#8212;"> 
    <!ENTITY percnt  "&#x0025;">
]>

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

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

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

    <authorgroup>
      <author>
        <firstname>Martin</firstname><othername>K.</othername>
           <surname>Petersen</surname>
        <affiliation>
          <address><email>mkp@mkp.net</email></address>
        </affiliation>
      </author>
      <author>
        <firstname>George</firstname><surname>Lebl</surname>
        <affiliation>
          <address><email>jirka@5z.com</email></address>
        </affiliation>
      </author>
      <author role="maintainer">
        <firstname>Brian</firstname><surname>Cameron</surname>
        <affiliation>
          <address><email>Brian.Cameron@Sun.COM</email></address>
        </affiliation>
      </author>
      <author>
        <firstname>Bill</firstname><surname>Haneman</surname>
        <affiliation>
          <address><email>Bill.Haneman@Sun.COM</email></address>
        </affiliation>
      </author>
    </authorgroup>
    <copyright>
      <year>1998</year><year>1999</year><holder>Martin K. Petersen</holder>
    </copyright>
    <copyright>
      <year>2001</year><year>2003</year><year>2004</year>
        <holder>George Lebl</holder>
    </copyright>
    <copyright>
      <year>2003</year> <holder>Red Hat, Inc.</holder>
    </copyright>
    <copyright>
      <year>2003</year><year>2004</year><holder>Sun Microsystems, Inc.</holder>
    </copyright>

    &legal;

    <releaseinfo>
       This manual describes version &version; of the MDM 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 MDM Display Manager.
      It was last updated on &date;.
    </para>  

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

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

    <para>
      mdm - The MDM Display Manager daemon (<command>mdm</command>).
    </para>

    <para>
      Greeter - The graphical login window (<command>mdmlogin</command> or
      <command>mdmgreeter</command> or <command>mdmwebkit</command>).
    </para>

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

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

    <para>
      Themed Greeter - The themable login window (<command>mdmgreeter</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>&lt;share&gt;/pixmaps</filename> if MDM was configured
      with <command>--prefix=/usr</command>.  Normally also note that
      MDM is installed with <command>--sysconfigdir=&lt;etc&gt;/X11</command>,
      meaning any path to which we refer to as
      <filename>&lt;etc&gt;/mdm/PreSession</filename> usually means
      <filename>&lt;etc/X11&gt;/mdm/PreSession</filename>.  Note that for
      interoperability it is recommended that you use a --prefix of
      <filename>/usr</filename> and a --sysconfdir of
      <filename>&lt;etc&gt;/X11</filename>.
    </para>
  </sect1>

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

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

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

      <para>
        Note that MDM is highly configurable, and many configuration
        settings can affect security.  Issues to be aware of are highlighted
        in this document and in the MDM Configuration files.
      </para> 
      
    </sect2>

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

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

      <para>
        Command-line interfaces for MDM programs installed to
        <filename>&lt;bin&gt;</filename> and <filename>&lt;sbin&gt;</filename>
        are considered stable.  Refer to your distribution documentation to see
        if there are any distribution-specific changes to these MDM interfaces
        and what support exists for them.
      </para>
         
    </sect2>

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

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

      <para>
        MDM can be asked to manage a display a number of ways.  Attached
        displays are always managed when MDM starts and will be restarted when
        a user's session is finished.  Remote displays can be requested via
        XDMCP, flexible displays via the <command>mdmflexiserver</command>
        command, and dynamic displays via the <command>mdmdynamic</command>
        command.  Displays that are started on request are not restarted on
        session exit.  
      </para>
        
      <para>
        When the MDM daemon is asked to manage a display, it will fork an
        X server process, then run the <filename>Init</filename> script as the
        root user, and start the login GUI dialog as a slave process on the
        display.  MDM can be configured to use either
        <command>mdmgreeter</command> (the default) or
        <command>mdmlogin</command> as the GUI dialog program.  The
        <command>mdmlogin</command> program supports accessibility while the
        <command>mdmgreeter</command> program supports greater themeability.
        The GUI dialog is run as the unpriviledged &quot;mdm&quot; user/group
        which is described in the &quot;Security&quot; section below.  The GUI
        dialog communicates with the daemon via a sockets protocol and via
        standard input/output.  The slave, for example passes the username and
        password information to the MDM daemon via standard input/output so
        the daemon can handle the actual authentication.
      </para>

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

      <para> 
        MDM uses Pluggable Authentication Modules (PAM) for
        authentication. After authenticating a user, the daemon runs the
        <filename>PostLogin</filename> script as root, and forks a slave
        process to start the requested session.  This slave process runs the
        <filename>PreSession</filename> script as root, sets up the user's
        environment, and starts the requested session.  MDM keeps track of the
        user's default session and language in the user's
        <filename>~/.dmrc</filename> and will use these defaults if the user
        did not pick a session or language in the login GUI. When the user's session exits, the MDM
        daemon will run the <filename>PostSession</filename> script as root.
      </para>

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

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

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

      <para>
        MDM supports three different display types: attached displays,
        flexible displays, and XDMCP remote displays.  The
        &quot;X Server Definitions&quot; subsection of the
        &quot;Configuration&quot; section explains how the X server is
        configured for different displays.
      </para>

      <para>
        Attached (also known as local or static) displays are always started by
        the daemon, and when they die or are killed, they are restarted.  MDM
        can run as many of these as needed.  MDM can also manage displays on
        which it does not manage a GUI login, thus MDM can be used for
        supporting X terminals.  The &quot;Attached DISPLAY Configuration&quot;
        subsection of the &quot;Configuration&quot; section describes how
        attached displays are defined.
      </para>

      <para>
        Flexible (also known as on-demand) displays are only available to users
        logged on the console.  Starting a flexible display will lock the
        current user session and will show a new login screen over the current
        running session.  If at least one flexible display is already running,
        and the user requests another, then a dialog will display showing
        existing flexible displays.  The user can choose to switch back to a
        previous display or start a new flexible display.  If the user switches
        back to a previous display, they will need to enter the password in the
        lock screen program to return to their session.  The MDM configuration
        file specifies the maximum number of flexible displays allowed on the
        system.
      </para>

      <para>
        Flexible displays may be started by running the
        <command>mdmflexiserver</command> command, or via calling the MDM
        socket protocol directly.  Some lock screen programs provide a button
        to start a new flexible session.  This allows a user to start a new
        session even if the screen was left locked. Flexible displays are not 
        restarted when the user session ends. Flexible displays require virtual 
        terminal (VT) support in the kernel. 
       </para>

       <para>
        The <filename>FlexibleXServers</filename>,
        <filename>FirstVT=7</filename>, <filename>VTAllocation</filename>,
        and <filename>FlexiReapDelayMinutes</filename> configuration settings
        are used to configure how flexible displays operate.
       </para>

       <para>
        Nested displays are available to users even if not logged in on the
        console.  Nested displays launch a login screen in a window in the 
        user's current session.  This can be useful if the user has more
        than one account on a machine and wishes to login to the other
        account without disrupting their current session.  Nested displays
        may be started by running the <command>mdmflexiserver -n</command>
        command or via calling the MDM socket protocol directly.  Nested
        displays require that the X server supports a nested X server command
        like Xnest or Xephyr.  The <filename>Xnest</filename> configuration
        option is used to configure how nested displays are started.
      </para>

      <para>
        The <command>mdmdynamic</command> is similar to
        <command>mdmflexiserver</command> in the sense that it allows the
        user to manage displays dynamically.  However displays started with
        <command>mdmdynamic</command> are treated as attached displays, so 
        they are restarted automatically when the session exits.  This 
        command is intended to be used in multi-user server environments
        (many displays connected to a single server).  In other words,
        this command allows the displays to be managed without hardcoding
        the display information in the &quot;Attached DISPLAY
        Configuration&quot; section of the configuration file.  This
        is useful to support the ability of adding new displays to the
        server without needing to restart MDM, for example.
      </para>

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

    </sect2>

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

      <para>
        The MDM daemon can be configured to listen for and manage X Display
        Manage Protocol (XDMCP) requests from remote displays.  By default
        XDMCP support is turned off, but can be enabled if desired.  If MDM is
        built with TCP Wrapper support, then the daemon will only grant access
        to hosts specified in the MDM service section in the TCP Wrappers
        configuration file.
      </para>

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

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

      <para>
        MDM can also be configured to honor INDIRECT queries and present a
        host chooser to the remote display.  MDM will remember the user's
        choice and forward subsequent requests to the chosen manager.  MDM
        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 MDM.  It is transparent and
        will be ignored by XDM or other daemons that implement XDMCP.
      </para>

      <para>
        If XDMCP seems to not be working, make sure that all machines are
        specified in <filename>/etc/hosts</filename>.
      </para>

      <para>
        Refer to the &quot;Security&quot; section for information about
        security concerns when using XDMCP.
      </para>
    </sect2>

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

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

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

      <para>
        The GTK+ Greeter is the default graphical user interface that is
        presented to the user. The greeter contains a menu at the top, an
        optional face browser, an optional logo and a text entry widget.
        This greeter has full accessibility support, and should be used
        by users with accessibility needs.
      </para>

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

      <para>
        The menu bar in the top of the greeter enables the user to select the
        requested session type/desktop environment, select an appropriate
        locale/language, halt/restart/suspend the computer, configure MDM
        (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 MDM user. See the <filename>Logo</filename> option in the
        reference section below for details.
      </para>
    </sect2>

    <sect2 id="themedgreeter">
      <title>The GDM Greeter</title>

      <para>
        The GDM Greeter is a greeter interface that takes up the whole
        screen and is very themable.  Themes can be selected and new themes
        can be installed by the configuration application or by setting the
        <filename>GraphicalTheme</filename> configuration key.  The Themed
        Greeter is much like the GTK+ Greeter in that it is controlled by
        the underlying daemon, is stateless, and is controlled by the
        daemon using the same simple protocol.
      </para>

      <para>
        The look and feel of this greeter is really controlled by the theme and
        so the user interface elements that are present may be different.  The
        only thing that must always be present is the text entry field as
        described above in the GTK+ Greeter.  The theme can include buttons
        that allow the user to select an appropriate locale/language,
        halt/restart/suspend the computer, configure MDM (given the user
        knows the root password), or start an XDMCP chooser.
      </para>

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

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

      <para>
        MDM supports a face browser which will display a list of users who
        can login and an icon for each user.  Starting with version 2.18.1
        the <filename>Browser</filename> configuration option must be set
        to &quot;true&quot; for this function to be available.  In previous
        versions it was only required when using the GTK+ Greeter.  When
        using the Themed Greeter, the Face Browser is only available if the
        MDM theme includes a &quot;userlist&quot; item type.
      </para>

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

      <para>
        The icons used by MDM 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 MDM user.  However, the daemon,
        proxies user pictures to the greeter and thus those do not have be be
        readable by the &quot;mdm&quot; user, but root.
      </para>

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

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

      <para>
        When the browser is turned on, valid usernames on the computer are
        inherently exposed to a potential intruder.  This may be a bad idea if
        you do not know who can get to a login screen.  This is especially
        true if you run XDMCP (turned off by default).
      </para>
    </sect2>

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

      <para>
        MDM itself will use syslog to log errors or status.  It can also log
        debugging information, which can be useful for tracking down problems
        if MDM is not working properly.  This can be enabled in the 
        configuration file.
      </para>

      <para>
        Output from the various X servers is stored in the MDM log directory,
        which is configurable, but is usually
        <filename>&lt;var&gt;/log/mdm/</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, MDM 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
        MDM message would be confusing and redundant.
      </para>

      <para>
        The session output is piped through the MDM daemon and so the
        <filename>~/.xsession-errors</filename> file is capped at about
        200 kilobytes by MDM to prevent a possible denial of service attack
        on the session.  An application could perhaps on reading some wrong
        data print out warnings or errors on the stderr or stdout.  This could
        perhaps fill up the user's home directory making it necessary to log
        out and back into their session to clear this.  This could be
        especially nasty if quotas are set.  MDM 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
        MDM 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 MDM can't open
        this file for some reason, then a fallback file will be created in the
        <filename>/tmp</filename> directory named
        <filename>/tmp/xses-&lt;user&gt;.XXXXXX</filename> where the
        <filename>XXXXXX</filename> are some random characters.
      </para>

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

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

      <para>
        In general MDM is very reluctant regarding reading/writing of user
        files (such as the <filename>~/.dmrc</filename>,
        <filename>~/.face</filename>,
        <filename>~/.xsession-errors</filename>, and
        <filename>~/.Xauthority</filename> files).  For instance it refuses to
        access anything but regular files.  Links, sockets and devices are
        ignored.  The value of the <filename>RelaxPermissions</filename>
        parameter determines whether MDM should accept files writable by the
        user's group or others.  These are ignored by default.
      </para>

      <para>
        All operations on user files are done with the effective user id of the
        user.  If the sanity check fails on the user's
        <filename>.Xauthority</filename> file, a fallback cookie is created in
        the directory specified by the <filename>UserAuthFBDir</filename>
        configuration setting (<filename>/tmp</filename> by default).
      </para>

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

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

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

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

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

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

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

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

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

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

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

      <para>
        For example, an effective way to implement such an exotic
        authentication mechanism would be to have a daemon running
        on the server listening to the authentication device (e.g.
        USB key, fingerprint reader, etc.).  When the device 
        announces that it has received input, then the daemon can
        set the <filename>PamStack</filename> configuration value
        using per-display configuration, and restart the greeter
        with the PAM stack that works with this device.  This avoids
        needing to hack the display manager code directly to support
        the feature.
      </para>
    </sect2>

    <sect2 id="utmpwtmp">
      <title>
        utmp/wtmp
      </title>

      <para>
        MDM generates utmp and wtmp User Accounting Database entries upon
        session login and logout.  The utmp database contains user access
        and accounting information that is accessed by commands such as
        <command>finger</command>, <command>last</command>,
        <command>login</command>, and <command>who</command>.  The wtmp
        database contains the history of user access and accounting 
        information for the utmp database.
      </para>

      <para>
        MDM 2.18 and earlier would run the X server <command>sessreg</command>
        program from the default MDM <command>PreSession</command> and
        <command>PostSession</command> scripts.  Starting with MDM 2.20, MDM
        interacts with the UTMP and WTMP databases directly and supports the
        following configuration options.
      </para>
        
      <para>
        When doing utmp processing, MDM supports configurability on how the
        ut_line value is set.  Programs that access the database assume that
        this value is an actual device, so MDM will set the device as follows.
        If the display is attached and has an associated Virtual Terminal (VT)
        device, then this device will be used.  Otherwise, if an attached
        display in the <command>[servers]</command> specifies a device name,
        then this value will be used.  Otherwise attached displays will default
        to the <filename>UtmpLineAttached</filename> value in the MDM
        configuration.  Remote displays will default to the 
        <filename>UtmpLineRemote</filename> value in the MDM configuration.
        Device values must begin with &quot;/dev/&quot;.
      </para>

      <para>
        MDM also supports the <filename>UtmpPseudoDevice</filename>
        configuration option.  If this configuration setting is true, then MDM
        will ensure that the specified device exists and will create a pseudo
        device if the device does not exist.  A pseudo device is a symlink to
        <filename>/dev/null</filename>.  If
        <filename>UtmpPseudoDevice</filename> is true, and the device does
        already exist, MDM checks to see if the device is a symlink to
        <filename>/dev/null</filename>.  If so, then MDM will update the access
        time of the symlink.  This ensures that programs that check the access
        time of the device will get a reasonable value for the last time the
        device was accessed.  If the <filename>UtmpPseudoDevice</filename>
        configuration option is false, then MDM will only set the ut_line
        value as specified regardless of whether the device exists or not.  
      </para>
    </sect2>

    <sect2 id="mdmuser">
      <title>The MDM User</title>

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

      <para>
        The MDM daemon normally runs as root, as does the slave.  However MDM
        should also have a dedicated user id and a group id which it uses for
        its graphical interfaces such as <command>mdmgreeter</command> and
        <command>mdmlogin</command>.  These are configured via the
        <filename>User</filename> and <filename>Group</filename>
        configuration options in the MDM configuration files.  The user and
        group should be created before running &quot;make install&quot;.  By
        default MDM assumes the user and the group are called &quot;mdm&quot;. 
      </para>

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

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

      <para>
        The danger is that someone who gains the MDM user/group privileges can
        then connect to any session.  So you should not, under any
        circumstances, make this some user/group which may be easy to get
        access to, such as the user <filename>nobody</filename>.  Users who
        gain access to the &quot;mdm&quot; user could also modify the Xauth
        keys causing Denial-Of-Service attacks.  Also if a person gains the
        ability to run programs as the user &quot;mdm&quot;, it would be
        possible to snoop on running MDM processes, including usernames and
        passwords as they are being typed in.  
      </para>

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

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

      <para>
        MDM by default doesn't trust the X server authorization directory and
        treats it in the same way as the temporary directory with respect to
        creating files.  This way someone breaking the MDM 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>
        MDM only supports the MIT-MAGIC-COOKIE-1 X server authentication
        scheme.  Normally little is gained from the other schemes, and no
        effort has been made to implement them so far.  Be especially
        careful about using XDMCP because the X server authentication cookie
        goes over the wire as clear text.  If snooping is possible, then an
        attacker could simply snoop your authentication password as you log in,
        regardless of the authentication scheme being used.  If snooping is
        possible and undesirable, then you should use ssh for tunneling an X
        connection rather then using XDMCP.  You could think of XDMCP as a sort
        of graphical telnet, having the same security issues.
      </para>

      <para>
        On the upside, MDM's random number generation is very conservative and
        MDM goes to extraordinary measures to truly get a 128 bit random
        number, using hardware random number generators (if available), plus
        the current time (in microsecond precision), a 20 byte array of
        pseudorandom numbers, process pid's, and other random information
        (possibly using <filename>/dev/audio</filename> or
        <filename>/dev/mem</filename> if hardware random generators are not
        available) to create a large buffer and then run MD5 digest on this.
        Obviously, all this work is wasted if you send this cookie over an open
        network or store it on an NFS directory (see
        <filename>UserAuthDir</filename> configuration key).  So be careful
        about where you use remote X display.
      </para>
    </sect2>

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

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

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

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

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

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

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

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

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

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

      <para>
        To workaround the inherent insecurity of XDMCP, mdm proposes a default
        built-in session that uses SSH to encrypt the remote connection.  See
        the section &quot;Securing remote connection through SSH&quot; above.
      </para>
    </sect2>

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

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

      <para>
        You should use the daemon name <command>mdm</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>
mdm: .evil.domain
</screen>
      <para>
        to <filename>&lt;etc&gt;/hosts.deny</filename>.  You may also need
        to add
      </para>
<screen>
mdm: .your.domain
</screen>
      <para>
        to your <filename>&lt;etc&gt;/hosts.allow</filename> if you normally
        disallow all services from all hosts.  See the
        <ulink type="help" url="man:hosts.allow">hosts.allow(5)</ulink> man
        page for details.
      </para>
    </sect2>

    <sect2 id="rbac">
      <title>RBAC (Role Based Access Control)</title>

      <para>
        If MDM is compiled with RBAC support, then the
        <filename>RBACSystemCommandKeys</filename> configuration option can be
        used to specify the RBAC key to be used to determine if the user has
        authority to use commands.  This is supported for the Shutdown,
        Reboot, Suspend, and Custom Commands that appear in the MDM greeter
        and via the <command>mdmflexiserver</command> QUERY_LOGOUT_ACTION,
        SET_LOGOUT_ACTION, and SET_SAFE_LOGOUT_ACTION commands.  The greeter
        will only display the option if the mdm user (specified by the
        <filename>User</filename> configuration option) has permission
        via RBAC.  Users will only be able to use the
        <command>mdmflexiserver</command> commands if the user has
        permission via RBAC.
      </para>
    </sect2>
  </sect1>

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

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

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

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

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

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

  </sect1>

  <sect1 id="mdmsetupusage">
    <title>Using mdmsetup To Configure MDM</title>

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

    <para>
      The <command>mdmsetup</command> program has five tabs: Local, Remote,
      Accessibility, Security, and Users, described below.  In parenthesis is
      information about which MDM configuration key is affected by each GUI
      choice.  Refer to the &quot;Configuration&quot; section of this manual
      and the comments in the MDM System Defaults Configuration File for
      additional details about each key.
    </para>

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

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

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

      <para>
        If the &quot;Style&quot; choice is &quot;Themed&quot;, then the 
        <command>mdmgreeter</command> program is used as the GUI
        (daemon/Greeter).  When this choice is selected,
        <command>mdmsetup</command> allows the user to select the theme to be
        used (greeter/GraphicalTheme).  Note that the checkbox to the left
        of the theme's name must be checked for a theme to be selected.
        Information about the theme's author and copyright are shown for the
        highlighted theme.  The &quot;Remove&quot; button can be used to delete
        the highlighted theme. The &quot;Add&quot; button can be used to add
        new themes to the system.  For a new theme to be added it must be
        in tar or compressed tar format.  The &quot;Background color&quot;
        displayed when MDM starts (and if the theme has transparent elements)
        can be selected (greeter/GraphicalThemedColor).  The &quot;Theme&quot;
        combo box may be set to &quot;Random from selected&quot; to display a
        random theme for each login (greeter/GraphicalThemeRand and
        greeter/GraphicalThemes).  To use random themes, select each theme that
        you wish to be displayed.  By default this combobox is set to
        &quot;Selected only&quot;, so that only a single theme may be selected
        and be used.
      </para>

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

      <para>
        Regardless of the &quot;Style&quot; choice, the user may also select
        whether the Actions menu is visible (greeter/SystemMenu), whether the
        Actions menu includes the choice to start <command>mdmsetup</command>
        (greeter/ConfigAvailable), and whether the Action menu includes the
        choice to start <command>mdmchooser</command> to run a remote XDMCP
        login session (greeter/ChooserButton).  The welcome message for 
        attached DISPLAYS may be specified (greeter/DefaultWelcome and
        greeter/Welcome). The welcome message may contain the character
        sequences described in the &quot;Text Node&quot; subsection of the
        &quot;Themed Greeter&quot; section of this manual.  These character
        sequences allow the welcome message to contain things like the display
        or host name.
      </para>
    </sect2>

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

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

      <para>
        If Remote login is enabled, then the welcome message for
        remote DISPLAYs may be specified (greeter/DefaultRemoteWelcome and 
        greeter/RemoteWelcome).  This welcome message is separate from the
        one shown for attached displays defined in the Local tab and can have
        a different value.  The welcome message may contain the character
        sequences described in the &quot;Text Node&quot; subsection of the
        &quot;Themed Greeter&quot; section of this manual.  These character
        sequences allow the welcome message to contain things like the
        display or host name.
      </para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <para> 
      MDM has powerful configuration management.  System default configuration
      is stored in the MDM System Defaults Configuration File and user changes
      to the default configuration are stored in the MDM Custom Configuration
      File.  This allows sysadmins to store the MDM System Defaults
      Configuration File on a shared filesystem, so a single file can be used
      to control configuration for multiple machines.  MDM also supports
      per-display configuration for GUI-related keys.
    </para>

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

    <para>
      Aside from the MDM System Defaults Configuration File, the other MDM
      configuration files are located, by default, in the
      <filename>&lt;etc&gt;/mdm/</filename> folder or its subdirectories.
      Note that the location of many configuration files are defined in the
      MDM configuration files, so check the MDM System Defaults Configuration
      File and the MDM Custom Configuration File if the files are not in the
      locations specified in this document.
    </para>

    <para>
      Listing of the config directory contents:
    </para>

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

    <para> 
      <filename>locale.alias</filename> is a file which looks much like the
      system locale alias but, in fact, is not the same.  This is a list
      of all languages that may be on your system.  All languages are
      checked to see if they exist before displaying them in the Language
      Selection dialog in the login GUI.  Only those that exist are displayed.
    </para>

    <para> 
      <filename>Xsession</filename> is a script which sets up a user session
      and then executes the user's choice of session.  Note that the session
      script is typically started via the <filename>desktop</filename>
      file associated with the session the user has picked.  Some 
      sessions may start the user's session via a different mechanism than
      the <filename>Xsession</filename> script, so please check the
      appropriate <filename>desktop</filename> before assuming a session
      startup issue is being caused by this file.
    </para>

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

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

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

    <para>
      A session can be disabled (if it was installed in
      <filename>&lt;share&gt;/xsessions/</filename>) by adding an identically
      named <filename>.desktop</filename> to one of the directories earlier in
      the path (likely <filename>&lt;etc&gt;/X11/sessions</filename>) and using
      <filename>Hidden=true</filename> in that file.
    </para>

    <para>
      MDM uses the optional key <filename>X-Mdm-XserverArgs</filename> in
      session files to specify additional arguments to be passed to the
      X server.  For example, the entry
      <filename>X-Mdm-XserverArgs=-depth 16</filename> will start the
      X server with a color depth of 16 bits.  Any such additional arguments
      are ignored when using a Nested display (when MDM is launched in a
      window).
    </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, MDM will try to run
        the script called <filename>Init/&lt;displayname&gt;</filename>. I.e.
        <filename>Init/:0</filename> for the first attached display.  If this
        file is not found, MDM will attempt to to run
        <filename>Init/&lt;hostname&gt;</filename>. I.e.
        <filename>Init/somehost</filename>.
        If this still is not found, MDM will try
        <filename>Init/XDMCP</filename> for all XDMCP logins or
        <filename>Init/Flexi</filename> for all on demand flexible
        displays.  If none of the above were found, MDM will run
        <filename>Init/Default</filename>. The script will be run as root and
        MDM blocks until it terminates. Use the <filename>Init/*</filename>
        script for applications that are supposed to run alongside with the MDM
        login window. xconsole for instance.  Commands to set the background
        etc. go in this file too.
      </para>

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

      <para>
        When the user has been successfully authenticated MDM 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 MDM side of things, MDM
        will run the scripts in the <filename>PreSession</filename> directory,
        again in the same manner as the <filename>Init</filename> directory.
        This script can be used for session management or accounting, for
        example.  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 MDM 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 MDM will look inside the file <filename>~/.dmrc</filename>
        for the stored preference.
      </para>

      <para>
        This script should really load the user's profile and generally do all
        the voodoo that is needed to launch a session.  Since many systems
        reset the language selections done by MDM, MDM will also set the
        <filename>$MDM_LANG</filename> variable to the selected language.  You
        can use this to reset the language environmental variables after you
        run the user's profile.  If the user elected to use the system language,
        then <filename>$MDM_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_MDM</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>$MDMSESSION</filename> set to the basename of the
        session that the user chose to run without the
        <filename>.desktop</filename> extension.  In addition
        <filename>$DESKTOP_SESSION</filename> is also set to the same value
        and in fact this will also be set by KDM in future versions.
      </para>

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

    <sect2 id="configfile">
      <title>The Configuration Files - MDM System Defaults Configuration File
             and MDM Custom Configuraiton File</title>
      
      <para>
        MDM uses two configuration files: the MDM System Defaults Configuration
        File (<filename>&lt;share&gt;/mdm/defaults.conf</filename>) and the
        MDM Custom Configuration File
        (<filename>&lt;etc&gt;/mdm/custom.conf</filename>).  The MDM System
        Defaults File contains the default configuration choices for MDM, and
        should not be modified by the user.  The MDM Custom Configuration File
        is where users may specify their custom configuration choices.  
        If a configuration option is not defined in either file, MDM will
        default to the value described in the comments in the MDM System
        Defaults Configuration File. 
      </para>

      <para>
        Both configuration files are divided into sections each containing
        variables that define the behavior for a specific part of the MDM
        suite.  Refer to the comments in the MDM System Defaults Configuration
        File for additional information about each configuration setting.
      </para>

      <para>
        MDM also supports per-display configuration for parameters in the
        &quot;gui&quot;, &quot;greeter&quot; sections of the configuration file
        Also the <filename>security/PamStack</filename> and
        <filename>daemon/LockScreen</filename> keys may be customized
        per-display.  Per-display configuration is specified by creating a file
        named
        <filename>&lt;etc&gt;/mdm/custom.conf&lt;display num&gt;</filename>.
        In this file the section and keys to use on this display can be 
        specified.  For example, configuration overrides for display
        &quot;:103&quot; would be stored in the file
        <filename>&lt;etc&gt;/mdm/custom.conf:0</filename>.  Per-display
        configuration is supported in MDM 2.14.6 and later.
      </para>

      <para>
        To change configuration by hand, edit the MDM Custom Configuration File
        or per-display configuration file and make sure the keyname=value
        pair you want is included in the appropriate section.  For example,
        to change the value for the &quot;Greeter&quot; key in the
        &quot;daemon&quot; section, make sure the daemon section of the MDM
        Custom Configuration File or per-display configuration file includes
        the &quot;[daemon]&quot; section followed by the key and value 
        change desired.  As in this example:
      </para>

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

      <para>
        The <command>mdmsetup</command> command can be used to modify the MDM
        Custom Configuration File.  Note the <command>mdmsetup</command> is
        intended to be run as root, so users who feel it is insecure to run
        GUI programs as root should edit the configuration files by hand.
      </para>

      <para>
        The MDM daemon <command>--config</command> argument may instead be used
        to specify a different configuration file location.  The MDM daemon
        must be restarted to change the configuration file being used.  Also
        when building MDM, the location of the configuration files may be
        specified via the <command>--with-defaults-conf</command> and
        <command>--with-custom-conf</command> configuration options.
      </para>

      <para>
        Previous to MDM 2.13.0.4 only the
        <filename>&lt;etc&gt;/mdm/mdm.conf</filename> existed.  For best
        backwards compatibility, this file will be used instead of the MDM
        Custom Configuration File if it exists on your system.  If upgrading
        to the new version of MDM, &quot;make install&quot; will check to see
        if the <filename>&lt;etc&gt;/mdm/mdm.conf</filename> file is different
        than the <filename>&lt;etc&gt;/mdm/factory-mdm.conf</filename> file.
        If so, the <filename>&lt;etc&gt;/mdm/mdm.conf</filename> file will be 
        automatically copied to
        <filename>&lt;etc&gt;/mdm/custom.conf</filename> to preserve any
        configuration changes.
      </para>
        
      <para>
        Distributions should edit the MDM System Defaults Configuration File to
        establish default configuration values, so that they are preserved as
        defaults and not modified by users modifying the MDM Custom
        Configuration File.  Note that distributions may modify the MDM System
        Defaults Configuration File on update to improve usability, security,
        etc.  So any changes made to this file may be lost.
      </para>

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

      <para>
        The following configuration keys are supported in MDM:
      </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>mdmgreeter</command> or
                <command>mdmlogin</command> to be launched with additional
                Gtk+ modules. This is useful when extra features are required
                such as accessible login. Note that only &quot;trusted&quot;
                modules should be used to minimize security issues.
              </para>
              <para>
                If true, then the registry daemon
                <command>at-spi-registryd</command>
                will be launched by <command>mdmgreeter</command> or
                <command>mdmlogin</command> starting with version MDM 2.17.
              </para>
              <para>
                Usually this is used for accessibility modules.  The modules
                which are loaded are specified with the
                <filename>GtkModulesList</filename> key.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>AllowLogoutActions</term>
            <listitem>
              <synopsis>AllowLogoutActions=HALT;REBOOT;SHUTDOWN;SUSPEND;CUSTOM_CMD</synopsis>
              <para>
                 Specify which actions are supported by the QUERY_LOGOUT_ACTION,
                 SET_LOGOUT_ACTION, and SET_SAFE_LOGOUT_ACTION
                 <command>mdmflexiserver</command> commands.  Valid values are 
                 HALT, REBOOT, SHUTDOWN, SUSPEND, and CUSTOM_CMD and these
                 should be separated by semicolons.  This allows certain
                 options to be disabled  if desired.  Refer to the related
                 <filename>SystemCommandsInMenu</filename> and
                 <filename>RBACSystemCommandKeys</filename> configuration
                 options.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>AlwaysLoginCurrentSession</term>
            <listitem>
              <synopsis>AlwaysLoginCurrentSession=true</synopsis>
              <para>
                If true, then when the user logs in and already has an
                existing session, then they are connected to that session
                rather than starting a new session.  This only works for
                sessions running on VTs (Virtual Terminals) started with
                mdmflexiserver, and not with XDMCP.  Note that VTs are not
                supported on all operating systems.
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>AutomaticLogin</term>
            <listitem>
              <synopsis>AutomaticLogin=</synopsis>
              <para>
                This user should be automatically logged in on first bootup.
                AutomaticLoginEnable must be true and this must be
                a valid user for this to happen.  &quot;root&quot; can never be
                autologged in however and mdm 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;/mdm/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 MDM, then you can check the presence of the
                <filename>MDMSESSION</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 MDM
                sessions.  Previously some scripts were checking for
                <filename>MDM_LANG</filename>, but that is only set when the
                user picks a non-system default language.
              </para>

              <para>
                This script should take care of doing the &quot;login&quot; for
                the user and so it should source the
                <filename>&lt;etc&gt;/profile</filename> and friends.  The
                standard script shipped with MDM 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;/mdmchooser</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;/mdmsetup --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 MDM 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, mdm will not display a message dialog on the
                console when an error happens.
              </para>
            </listitem>
          </varlistentry>
                             
          <varlistentry>
            <term>DefaultPath</term>
            <listitem>
              <synopsis>DefaultPath=defaultpath (value set by configure)</synopsis>
              <para>
                Specifies the path which will be set in the user's session.
                This value will be overridden with the value from
                <filename>/etc/default/login</filename> if it contains
                &quot;ROOT=&lt;pathname&gt;&quot;.  If the
                <filename>/etc/default/login</filename> file exists, but
                contains no value for ROOT, the value as defined in the MDM
                configuration will be be used.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DefaultSession</term>
            <listitem>
              <synopsis>DefaultSession=gnome.desktop</synopsis>
              <para>
                The session that is used by default if the user does not have
                a saved preference and has picked 'Last' from the list of
                sessions.  Note that 'Last' need not be displayed, see
                the <filename>ShowLastSession</filename> key.
              </para>
            </listitem>
          </varlistentry>
          
          
          <varlistentry>
            <term>DisplayInitDir</term>
            <listitem>
              <synopsis>DisplayInitDir=&lt;etc&gt;/mdm/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 MDM 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 MDM).  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, MDM will warn the user if they are already logged in
                on another virtual terminal.  On systems where MDM supports
                checking the X virtual terminals, MDM 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 MDM daemon will honor requests to manage
                displays via the <filename>/tmp/.mdm_socket</filename>
                socket connection. Displays can be created, started,
                and deleted with the appropriate commands. The
                <filename>mdmdynamic</filename> command is a convenient
                method to send these messages.
              </para>
            </listitem>
          </varlistentry>

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

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

          <varlistentry>
            <term>FlexibleXServers</term>
            <listitem>
              <synopsis>FlexibleXServers=5</synopsis>
              <para>
                The maximum number of allowed flexible displays.  These are
                displays that can be run using the
                <filename>/tmp/.mdm_socket</filename> socket connection.
                This is used for both full flexible displays and for nested
                displays (refer to the <filename>Xnest</filename> configuration
                option).
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>Greeter</term>
            <listitem>
              <synopsis>Greeter=&lt;bin&gt;/mdmlogin</synopsis>
              <para>
                Full path and name of the greeter executable followed by
                optional arguments.  This is the greeter used for all displays
                except for the XDMCP remote displays.  See also
                <filename>RemoteGreeter</filename>
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Group</term>
            <listitem>
              <synopsis>Group=mdm</synopsis>
              <para>
                The group name under which <command>mdmlogin</command>,
                <command>mdmgreeter</command>,
                <command>mdmchooser</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 MDM
                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.mdm</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>mdmgreeter</command> or <command>mdmlogin</command>
                will be invoked with if <filename>AddGtkModules</filename> is
                true.  The format is the same as the standard Gtk+ module
                interface.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>HaltCommand</term>
            <listitem>
              <synopsis>HaltCommand=&lt;sbin&gt;/shutdown -h now</synopsis>
              <para>
                Full path and arguments to command to be executed when user
                selects &quot;Shut Down&quot; from the Actions menu.  This can
                be a ';' separated list of commands to try.  If a value is
                missing, the shut down command is not available.  Note that the
                default for this value is not empty, so to disable
                &quot;Shut Down&quot; it must be
                set to an empty value.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>KillInitClients</term>
            <listitem>
              <synopsis>KillInitClients=true</synopsis>
              <para>
                Determines whether MDM 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/mdm</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>PreFetchProgram</term>
            <listitem>
              <synopsis>PreFetchProgram=command</synopsis>
              <para>
                Program to be run by the MDM greeter/login program when the
                initial screen is displayed.  The  purpose is to provide a hook
                where files which will be used after login can be preloaded to
                speed performance for the user.  The program will be called
                once only, the first time a greeter is displayed.  The
                mdmprefetch command may be used.  This utility will load any
                libraries passed in on the command line, or if the argument
                starts with a &quot;@&quot; character, it will process the file
                assuming it is an ASCII file containing a list of libraries,
                one per line, and load each library in the file.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>PamStack</term>
            <listitem>
              <synopsis>PamStack=mdm</synopsis>
              <para>
                If using PAM, this specifies the PAM service name to use when
                calling pam_start.  This option may be configured per-display
                so that MDM can be configured to have a different PAM stack
                on a given display.  Note that autologin sessions append
                &quot;-autologin&quot; to this value, so by default autologin
                sessions use the service name &quot;mdm-autologin&quot;.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>PostLoginScriptDir</term>
            <listitem>
              <synopsis>PostLoginScriptDir=&lt;etc&gt;/mdm/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;/mdm/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;/mdm/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>RBACSystemCommandKeys</term>
            <listitem>
              <synopsis>RBACSystemCommandKeys</synopsis>
              <para>
                 Support RBAC (Role Based Access Control) for system commands 
                 (Shutdown, Reboot, Suspend, etc.).  This feature is only
                 functional if MDM is compiled with RBAC support.  Specify the
                 RBAC key used to determine if the user has permission to use
                 the action via the QUERY_LOGOUT_ACTION, SET_LOGOUT_ACTION, and
                 SET_SAFE_LOGOUT_ACTION <command>mdmflexiserver</command>
                 commands.  Valid actions are HALT, REBOOT, SUSPEND, and
                 CUSTOM_CMD.  The greeter will only display the command if the
                 mdm user (<filename>User</filename> configuration key) has
                 RBAC permissions to use the action.  RBAC keys for multiple
                 actions can be specified by separating them with semicolons.
                 The format for each is "Action:RBAC key".  If an action is not
                 specified, it is assumed that all users have permission to use
                 this action.  For example, a valid value for this
                 configuration option would be
                 &quot;HALT:key.for.halt;REBOOT:key.for.reboot&quot;.  Refer to
                 the related <filename>AllowLogoutActions</filename> and
                 <filename>SystemCommandsInMenu</filename> configuration
                 options.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>RebootCommand</term>
            <listitem>
              <synopsis>RebootCommand=&lt;sbin&gt;/shutdown -r now</synopsis>
              <para>
                Full path and optional arguments to the command to be
                executed when user selects Restart from the Actions menu.  This
                can be a ';' separated list of commands to try.  If missing,
                the restart command is not available.  Note that the default 
                for this value is not empty so to disable restart you must set
                this explicitly to an empty value.
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>SoundProgram</term>
            <listitem>
              <synopsis>SoundProgram=<filename>&lt;bin&gt;/play</filename> (or <filename>&lt;bin&gt;/audioplay</filename> on Solaris)</synopsis>
              <para>
                Application to use when playing a sound.  Currently used for
                playing the login sound, see the
                <filename>SoundOnLoginFile</filename> key.  Supported since
                2.5.90.0.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>StandardXServer</term>
            <listitem>
              <synopsis>StandardXServer=/dir/to/X (value assigned by configuration file)</synopsis>
              <para>
                Full path and arguments to the standard X server command.
                This is used when mdm 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>SystemCommandsInMenu</term>
            <listitem>
              <synopsis>SuspendCommand=HALT;REBOOT;SHUTDOWN;SUSPEND;CUSTOM_CMD</synopsis>
              <para>
                 Specify which system commands are available in the greeter
                 menu. Valid values are HALT, REBOOT, SHUTDOWN, SUSPEND, and
                 CUSTOM_CMD and these should be separated by semicolons.  This
                 can be useful if you want to disable some options in the menu,
                 but still have them available to authenticated users via the
                 SET_LOGOUT_ACTION or SET_SAFE_LOGOUT_ACTION
                 <command>mdmflexiserver</command> commands.  For example, the
                 GNOME panel uses these commands to provide Shutdown, Reboot,
                 and Suspend in the application menu.  Therefore if you turn
                 off these options in the greeter, these options can still be
                 available to users who have authenticated via the GNOME panel.
                 Refer to the related
                 <filename>AllowLogoutActions</filename> and
                 <filename>RBACSystemCommandKeys</filename> configuration
                 options.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>TimedLoginEnable</term>
            <listitem>
              <synopsis>TimedLoginEnable=false</synopsis>
              <para>
                 If the user given in <filename>TimedLogin</filename> should be
                logged in after a number of seconds (set with
                <filename>TimedLoginDelay</filename>) of inactivity on the
                login screen.  This is useful for public access terminals or
                perhaps even home use.  If the user uses the keyboard or
                browses the menus, the timeout will be reset to 
                <filename>TimedLoginDelay</filename> or 30 seconds, whichever 
                is higher.   If the user does not enter a username but just
                hits the ENTER key while the login program is requesting the
                username, then MDM will assume the user wants to login
                immediately as the timed user.  Note that no password will be
                asked for this user so you should be careful, although if using
                PAM it can be configured to require password entry before
                allowing login.
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>TimedLoginDelay</term>
            <listitem>
              <synopsis>TimedLoginDelay=30</synopsis>
              <para>
                Delay in seconds before the <filename>TimedLogin</filename>
                user will be logged in.  It must be greater then or equal to 10.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>User</term>
            <listitem>
              <synopsis>User=mdm</synopsis>
              <para>
                The username under which <command>mdmlogin</command>,
                <command>mdmgreeter</command>,
                <command>mdmchooser</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 MDM
                data and it should not therefore be a user such as nobody, but
                rather a dedicated user.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>UserAuthDir</term>
            <listitem>
              <synopsis>UserAuthDir=</synopsis>
              <para>
                The directory where user's <filename>.Xauthority</filename>
                file should be saved.  When nothing is specified the user's
                home directory is used.  This is tilde expanded so you
                can set it to things like: <filename>~/authdir/</filename>.
              </para>

              <para>
                If you do not use the tilde expansion, then the filename
                created will be random, like in
                <filename>UserAuthFBDir</filename>.  This way many users can
                have the same authentication directory.  For example you might
                want to set this to <filename>/tmp</filename> when user has the
                home directory on NFS, since you really don't want cookie files
                to go over the wire.  The users should really have write
                privileges to this directory, and this directory should really
                be sticky and all that, just like the <filename>/tmp</filename>
                directory.
              </para>

              <para>
                Normally if this is the user's home directory MDM 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 MDM 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 MDM supports automatic VT (virtual terminal)
                allocation (currently Linux and FreeBSD only), you can have
                MDM 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;/mdm/XKeepsCrashing</synopsis>
              <para>
                A script to run in case X keeps crashing.  This is for running
                An X configuration or whatever else to make the X configuration
                work.  See the script that came with the distribution for an
                example.  The distributed <filename>XKeepsCrashing</filename>
                script is tested on Red Hat, but may work elsewhere.  Your
                system integrator should make sure this script is up to date
                for your particular system.
              </para>
              <para>
                In case <filename>FailsafeXServer</filename> is setup, that
                will be tried first.  and this only used as a backup if even
                that X server keeps crashing.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Xnest</term>
            <listitem>
              <synopsis>Xnest=&lt;bin&gt;/X11/Xephyr -audit 0</synopsis>
              <para>
                The full path and arguments to the nested X server command, 
                which can be Xephyr, Xnest, or similar program.  This command
                is used for starting nested displays allowing the user
                to start new login screens in a nested window.  Xephyr is
                recommended since it works best and better supports modern
                X server extensions.  Therefore MDM will set the default
                configuration to use Xephyr if available.  If Xephyr is not
                available, then Xnest will be used if it is available.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>XnestUnscaledFontPath</term>
            <listitem>
              <synopsis>XnestUnscaledFontPath=true</synopsis>
              <para>
                Set to true if the nested X server command program supports the
                ":unscaled" suffix in the FontPath (passed to nested X server
                command via the -fp argument).  Some Xnest (e.g. Xsun Xnest)
                programs do not, and it is necessary to set this to false for
                such nested X server commands to work with MDM.  Refer to the
                <filename>Xnest</filename> configuration option.
              </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 MDM.  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 MDM.
                This value should be set to true to allow such logins.
                Remote logins are any logins that come in through the XDMCP.
              </para>
              <para>
                On systems that support PAM, this parameter is not as useful
                since you can use PAM to do the same thing, and do even
                more.
              </para>
              <para>
                This value will be overridden and set to false if the
                <filename>/etc/default/login</filename> file exists and
                contains &quot;CONSOLE=/dev/login&quot;, and set to true if the
                <filename>/etc/default/login</filename> file exists and
                contains any other value or no value for CONSOLE.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>AllowRemoteAutoLogin</term>
            <listitem>
              <synopsis>AllowRemoteAutoLogin=false</synopsis>
              <para>
                Allow the timed login feature to work for remote displays.
                In other words, remote connections via XDMCP will be allowed to
                log into the &quot;TimedLogin&quot; user after the delay
                defined by <filename>TimedLoginDelay</filename>.
              </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 MDM checks the ownership of the home directories
                before writing to them, this prevents security issues in case
                of bad setup.  However in some instances home directories will
                be owned by a different user and in this case it is necessary
                to turn this option on.  You will also most likely have to
                turn the <filename>RelaxPermissions</filename> key to at least
                value 1 since in such a scenario home directories are likely
                to be group writable.  Supported since 2.6.0.4.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>SupportAutomount</term>
            <listitem>
              <synopsis>SupportAutomount=false</synopsis>
              <para>
                By default MDM checks the ownership of the home directories
                before writing to them, this prevents security issues in case
                of bad setup.  However, when home directories are managed by
                automounter, they are often not mounted before they are 
                accessed. This option works around subtleties of Linux
                automounter.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DisallowTCP</term>
            <listitem>
              <synopsis>DisallowTCP=true</synopsis>
              <para>
                If true, then always append <filename>-nolisten tcp</filename>
                to the command line when starting attached X servers, thus
                disallowing TCP connection.  This is a more secure
                configuration if not using remote connections.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>NeverPlaceCookiesOnNFS</term>
            <listitem>
              <synopsis>NeverPlaceCookiesOnNFS=true</synopsis>
              <para>
                Normally if this is true (which is by default), MDM will not
                place cookies into the user's home directory if this directory
                is on NFS.  Well, MDM 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 MDM.  This value will be
                overridden with the value from
                <filename>/etc/default/login</filename> if it contains
                &quot;PASSREQ=[YES|NO]&quot;.  If the
                <filename>/etc/default/login</filename> file exists, but
                contains no value for PASSREQ, the value as defined in the MDM
                configuration will be used.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>RelaxPermissions</term>
            <listitem>
              <synopsis>RelaxPermissions=0</synopsis>
              <para>
                By default MDM 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 MDM should wait before reactivating the
                entry field after a failed login.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>UserMaxFile</term>
            <listitem>
              <synopsis>UserMaxFile=65536</synopsis>
              <para>
                MDM will refuse to read/write files bigger than this number
                (specified in bytes).
              </para>
              
              <para>
                In addition to the size check MDM 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>
          <varlistentry>
            <term>UtmpLineAttached</term>
            <listitem>
              <synopsis>UtmpLineAttached=/dev/console (or /dev/dtlocal on Solaris)</synopsis>
              <para>
                When doing Utmp processing for attached displays, MDM sets the
                ut_line to the device associated with the Virtual Terminal (VT)
                if it is being used.  Otherwise, it will use the value
                specified with the display in the
                <filename>[servers]</filename> section if a value is provided.
                If not, then the default value specified in UtmpLineAttached is
                used for attached displays.  The value can contain
                &quot;%d&quot; which is translated to the DISPLAY value or
                &quot;%h&quot; which is translated to the hostname.  This value
                must begin with <filename>/dev/</filename>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>UtmpLineRemote</term>
            <listitem>
              <synopsis>UtmpLineRemote= (or /dev/dtremote on Solaris)</synopsis>
              <para>
                When doing Utmp processing, MDM sets the ut_line to this value
                for remote displays.  The value can contain &quot;%d&quot;
                which is translated to the DISPLAY value or &quot;%h&quot;
                which is translated to the hostname.  This value must begin
                with <filename>/dev/</filename>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>UtmpPseudoDevice</term>
            <listitem>
              <synopsis>PseudoDevice=false (or true on Solaris)</synopsis>
              <para>
                If the device associated with a display does not exist, then
                MDM will create a symlink to <filename>/dev/null</filename>, or
                touch it if it is a symlink to <filename>/dev/null</filename>.
                Some programs such as <command>last</command>,
                <command>finger</command>, or <command>who</command> access the
                utmp database and may assume that the device points to an
                actual file.  Creating such symlinks ensures that such programs
                work properly.
              </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, MDM
                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 attached DISPLAYS allowed is not 
                limited.  Only remote connections via XDMCP are limited by
                this configuration option.
              </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 MDM.
              </para>
              
              <para>
                <filename>mdm</filename> listens for requests on UDP port 177.
                See the Port option for more information.
              </para>
              
              <para>
                If MDM is compiled to support it, access from remote displays
                can be controlled using the TCP Wrappers library. The service
                name is <filename>mdm</filename>
              </para>
              
              <para>
                You should add 
<screen>
mdm:.my.domain
</screen>
                to your <filename>&lt;etc&gt;/hosts.allow</filename>, depending
                on your TCP Wrappers configuration.  See the
                <ulink type="help" url="man:hosts.allow">hosts.allow(5)</ulink>
                man page for details.
              </para>
              
              <para>
                Please note that XDMCP is not a particularly secure protocol
                and that it is a good idea to block UDP port 177 on your
                firewall unless you really need it.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>EnableProxy</term>
            <listitem>
              <synopsis>EnableProxy=false</synopsis>
              <para>
                Setting this to true enables support for running XDMCP sessions
                on a local proxy X server. This may improve the performance of
                XDMCP sessions, especially on high latency networks, as many
                X protocol operations can be completed without going over the
                network.
              </para>
              <para>
                Note, however, that this mode will significantly increase the
                burden on the machine hosting the XDMCP sessions
              </para>
              <para>
                See the <filename>FlexiProxy</filename> and
                <filename>FlexiProxyDisconnect</filename> options for further
                 details on how to configure support for this feature.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>HonorIndirect</term>
            <listitem>
              <synopsis>HonorIndirect=true</synopsis>
              <para>
                Enables XDMCP INDIRECT choosing (i.e. remote execution of
                <filename>mdmchooser</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, MDM 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>
                MDM 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 MDM 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>
                MDM 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, MDM 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>mdm</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 MDM in the past used to have a
                <filename>PingInterval</filename> configuration key which was
                also in minutes.  For most purposes you'd want this setting
                to be lower then one minute however since in most cases where
                XDMCP would be used (such as terminal labs), a lag of more
                than 15 or so seconds would really mean that the terminal was
                turned off or restarted and you would want to end the session.
              </para>
            </listitem>
          </varlistentry>

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

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

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

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

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

          <varlistentry>
            <term>AllowGtkThemeChange</term>
            <listitem>
              <synopsis>AllowGtkThemeChange=true</synopsis>
              <para>
                If to allow changing the GTK+ (widget) theme from the greeter.
                Currently this only affects the standard greeter as the
                graphical greeter does not yet have this ability.
                The theme will stay in effect on this display until changed
                and will affect all the other windows that are put up by MDM.
                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 MDM 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 MDM.  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=#000000</synopsis>
              <para>
                If the BackgroundType is 2, use this color in the background
                of the greeter.  Also use it as the back of transparent images
                set on the background and if the BackgroundRemoteOnlyColor
                is set and this is a remote display.
                This only affects the GTK+ Greeter.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>BackgroundProgramInitialDelay</term>
            <listitem>
              <synopsis>BackgroundProgramInitialDelay=30</synopsis>
              <para>
                The background application will be started after at least that
                many seconds of inactivity.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>RestartBackgroundProgram</term>
            <listitem>
              <synopsis>RestartBackgroundProgram=true</synopsis>
              <para>
                If set the background application will be restarted when it has
                exited, after the delay described below has elapsed.  This
                option can be useful when you wish to run a screen saver 
                application when no user is using the computer.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>BackgroundProgramRestartDelay</term>
            <listitem>
              <synopsis>BackgroundProgramRestartDelay=30</synopsis>
              <para>
                The background application will be restarted after at least that 
                many seconds of inactivity.
              </para>
            </listitem>
          </varlistentry>

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

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

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

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

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

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

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

          <varlistentry>
            <term>ConfigAvailable</term>
            <listitem>
              <synopsis>ConfigAvailable=false</synopsis>
              <para>
                If true, allows the configurator to be run from the greeter.
                Note that the user will need to type in the root password
                before the configurator will be started.  This is set to 
                false by default for additional security.  See the
                <filename>Configurator</filename> option in the daemon
                section.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>DefaultFace</term>
            <listitem>
              <synopsis>DefaultFace=&lt;share&gt;/pixmaps/nophoto.png</synopsis>
              <para>
                If a user has no defined face image, MDM will use the
                &quot;stock_person&quot; icon defined in the current GTK+
                theme.  If no such image is defined, the image specified by 
                <filename>DefaultFace</filename> will be used.  The image must
                be in a gdk-pixbuf supported format and the file must be
                readable to the MDM 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>mdmsetup</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>mdmsetup</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 MDM user.
              </para>
              
              <para>
                A user's own icon file will always take precedence over the
                sysadmin provided one.
              </para>
            </listitem>
          </varlistentry>

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

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

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

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

         <varlistentry>
            <term>GraphicalThemedColor</term>
            <listitem>
              <synopsis>GraphicalThemedColor=#000000</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;/mdm/locale.alias</synopsis>
              <para>
                File in format similar to the GNU locale format with entries
                for all supported languages on the system.  The format is
                described above or in a comment inside that file.
              </para>
            </listitem>
          </varlistentry>

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

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

          <varlistentry>
            <term>MinimalUID</term>
            <listitem>
              <synopsis>MinimalUID=100</synopsis>
              <para>
                The minimal UID that MDM 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>mdmlogin</command> should
                shake the display when an incorrect username/password is
                entered.
                This only affects the GTK+ Greeter.
              </para>
            </listitem>
          </varlistentry>

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

          <varlistentry>
            <term>RemoteWelcome</term>
            <listitem>
              <synopsis>RemoteWelcome=Welcome to &percnt;n</synopsis>
              <para>
                Controls which text to display next to the logo image in the
                greeter for remote XDMCP sessions.  The same expansion is
                done here as in the <filename>Welcome</filename> string.
                This string can use the same special character sequences as
                explained in the &quot;Text Node&quot; section of the
                &quot;Themed Greeter&quot; chapter.
                chapter.
              </para>
            </listitem>
          </varlistentry>

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

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

          <varlistentry>
            <term>SoundOnLogin</term>
            <listitem>
              <synopsis>SoundOnLogin=true</synopsis>
              <para>
                If true, the greeter will play a sound or beep when it is
                ready for a login.  See also the
                <filename>SoundOnLoginFile</filename> key.
                Supported since 2.5.90.0.
              </para>
            </listitem>
          </varlistentry>

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

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

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

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

          <varlistentry>
            <term>SoundOnLoginFailureFile</term>
            <listitem>
              <synopsis>SoundOnLoginFailureFile=/path/to/sound.wav</synopsis>
              <para>
                The file that will be played using the specified sound
                application (by default that is
                <filename>/usr/bin/play</filename>) after a failed login 
                attempt.  See also the <filename>SoundOnLoginFailure</filename>
                key and the <filename>SoundProgram</filename> key.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>SystemMenu</term>
            <listitem>
              <synopsis>SystemMenu=true</synopsis>
              <para>
                Turns the Actions menu (which used to be called System menu) on
                or off.  If this is off then one of the actions will be
                available anywhere.  These actions include Shutdown, Restart,
                Configure, XDMCP chooser and such.  All of those can however
                be turned off individually.  Shutdown, Restart and Suspend can
                be turned off by just setting the corresponding keys to empty.
                Note that the actions menu is only shown on attached displays.
                It would not be safe or even desirable on remote logins, so you
                do not have to worry about remote users having these privileges.
              </para>

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

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

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

          <varlistentry>
            <term>UseInvisibleInEntry</term>
            <listitem>
              <synopsis>UseInvisibleInEntry=false</synopsis>
              <para>
                Do not show any visual feedback is the password entry.
                This is the standard in console and xdm. Settings this
                option discards the <filename>UseCirclesInEntry</filename>
                option.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DefaultWelcome</term>
            <listitem>
              <synopsis>DefaultWelcome=true</synopsis>
              <para>
                If set to true, the value &quot;Welcome&quot; is used for the
                <filename>Welcome</filename>.  This value is translated
                into the appropriate language for the user.  If set to
                false, the <filename>Welcome</filename> setting is used.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Welcome</term>
            <listitem>
              <synopsis>Welcome=Welcome</synopsis>
              <para>
                Controls which text to display next to the logo image in the
                standard greeter. The following control chars are supported:
              </para>
              
              <para>
                &percnt;&percnt; &mdash; the `&percnt;' character
              </para>
              
              <para>
                &percnt;d &mdash; display's hostname
              </para>
              
              <para>
                &percnt;h &mdash; Fully qualified hostname
              </para>

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

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

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

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

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

      <sect3 id="choosersection">
        <title>XDCMP Chooser Options</title>

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

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

          <varlistentry>
            <term>Broadcast</term>
            <listitem>
              <synopsis>Broadcast=true</synopsis>
              <para>
                If true, the chooser will broadcast a query to the local
                network and collect responses.  This way the chooser will
                always show all available managers on the network.  If you
                need to add some hosts not local to this network, or if you
                don't want to use a broadcast, you can list them explicitly
                in the <filename>Hosts</filename> key.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>Multicast</term>
            <listitem>
              <synopsis>Multicast=true</synopsis>
              <para>
                If true and IPv6 is enabled, the chooser will send a multicast
                query to the local network and collect responses from the hosts
                who have joined multicast group. If you don't want to send a
                multicast, you can specify IPv6 address in the <filename>Hosts
                </filename> key. The host will respond if it is listening to
                XDMCP requests and IPv6 is enabled there.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>MulticastAddr</term>
            <listitem>
              <synopsis>MulticastAddr=ff02::1</synopsis>
              <para>
                This is the Link-local Multicast address and is hardcoded here.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>DefaultHostImage</term>
            <listitem>
              <synopsis>DefaultHostImage=&lt;share&gt;/pixmaps/nohost.png</synopsis>
              <para>
                File name for the default host icon. This image will be
                displayed if no icon is specified for a given host. The
                file must be in a gdk-pixbuf supported format and it must be
                readable for the MDM 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>mdmchooser</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 MDM 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 MDM.  This output 
                tends to be verbose so should not be turned on for general
                use.
              </para>
            </listitem>
          </varlistentry>

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

      <sect3 id="customcmdsection">
        <title>Custom Commands</title>
        
        <para>
          You can create up to 10 different commands. Gaps between command
          numbers are allowed and their relative positioning within the
          section and with respect to each other is not important as long as
          they conform to the permitted range of [0-9].
          
        </para>
          
        <variablelist>
          <title>[customcommand]</title>
          
          <varlistentry>
            <term>CustomCommand[0-9]</term>
            <listitem>
              <synopsis>CustomCommand[0-9]=</synopsis>
              <para>
                Full path and arguments to command to be executed when user
                selects <filename>n-th</filename> &quot;Custom Command&quot;
                from the Actions menu.  This can be a ';' separated list of
                commands to try.  If the value is empty or missing, then the
                custom command is not available.  By default this value is not
                enabled, so to enable &quot;Custom Command&quot; it must be
                set to a nonempty value.  [0-9] represents the
                <filename>CustomCommand</filename> suffix and can be an
                integer between 0 and 9. 
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandIsPersistent[0-9]</term>
            <listitem>
              <synopsis>CustomCommandIsPersistent[0-9]=</synopsis>
              <para>
                Specifies if <filename>n-th</filename> &quot;Custom
                Command&quot; will appear outside the login manager, for
                example on the desktop through the Log Out/Shut Down dialogs.
                If not specified the default value is &quot;false&quot;. This
                option is only valid if corresponding
                <filename>CustomCommand</filename> is defined. [0-9] represents
                <filename>CustomCommand</filename> suffix and can be an integer
                between 0 and 9.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandLabel[0-9]</term>
            <listitem>
              <synopsis>CustomCommandLabel[0-9]=</synopsis>
              <para>
                Specifies the stock label that will be displayed on the
                <filename>n-th</filename> &quot;Custom Command&quot;
                buttons and menu items. If not specified the default value is
                &quot;Custom_[0-9]&quot;. This option is only valid if
                corresponding <filename>CustomCommand</filename> is defined. 
                [0-9] represents <filename>CustomCommand</filename> suffix
                and can be an integer between 0 and 9. This option can't contain
                any semicolon characters (i.e. &quot;;&quot;).
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandLRLabel[0-9]</term>
            <listitem>
              <synopsis>CustomCommandLRLabel[0-9]=</synopsis>
              <para>
                Specifies the stock label that will be displayed on the
                <filename>n-th</filename> &quot;Custom Command&quot;
                list items and radio buttons.  If not specified the default
                value is  &quot;Execute custom command _[0-9]&quot;. This 
                option is only valid if corresponding
                <filename>CustomCommand</filename> is defined.  [0-9]
                represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandNoRestart[0-9]</term>
            <listitem>
              <synopsis>CustomCommandNoRestart[0-9]=</synopsis>
              <para>
                Specifies if mdm will be stopped/restarted once
                <filename>n-th</filename> &quot;Custom Command&quot;
                has been executed. If not specified the default value is
                &quot;false&quot;. This option is only valid if corresponding
                <filename>CustomCommand</filename> is defined.  [0-9]
                represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9. In addition when
                corresponding <filename>CustomCommandIsPersistent</filename> 
                is set to true,  setting CustomCommandNoRestart to false will
                place corresponding <filename>CustomCommand</filename> in the 
                Shut Down dialog set of actions, setting it to true will place
                corresponding 
                <filename>CustomCommand</filename> in the Log Out dialog set of
                actions.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandText[0-9]</term>
            <listitem>
              <synopsis>CustomCommandText[0-9]=</synopsis>
              <para>
                Specifies the message that will be displayed on the warning
                dialog box once <filename>n-th</filename>
                &quot;Custom Command&quot; button/menu item/radio button/list
                item has been activated.  If not specified the default value is
                &quot;Are you sure?&quot;. This option is only valid if
                corresponding <filename>CustomCommand</filename> is defined.
                [0-9] represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>CustomCommandTooltip[0-9]</term>
            <listitem>
              <synopsis>CustomCommandTooltip[0-9]=</synopsis>
              <para>
                Specifies the message that will be displayed on tooltips for
                <filename>n-th</filename> &quot;Custom Command&quot;
                entries. If not specified the default value is  &quot;Execute
                custom command [0-9]&quot;. This option is only valid if
                corresponding <filename>CustomCommand</filename> is defined.
                [0-9] represents <filename>CustomCommand</filename> suffix and
                can be an integer between 0 and 9.
              </para>
            </listitem>
          </varlistentry>         
        </variablelist>
      </sect3>
          
      <sect3 id="xserverdefs">
        <title>X Server Definitions</title>

        <para>
          MDM needs to be provided with information about each X servers that
          will be used.  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, MDM will assume default values for a 'Standard' server
          and the path given by <filename>daemon/StandardXServer</filename>.
          <filename>Standard</filename> is used as the default,
          in situations when no other server has been defined.
        </para>

        <para>
          Servers are defined by sections named <filename>server-</filename>
          followed by the identifier of this server.  This should be a simple
          ASCII string with no spaces.  The GUI configuration program allows
          users to edit the servers defined in the MDM configuration files
          but currently does not allow adding or deleting entries.  Like
          normal configuration options, <filename>server-</filename>
          sections in the <filename>&lt;etc&gt;/mdm/custom.conf</filename>
          file override values in the
          <filename>&lt;share&gt;/mdm/defaults.conf</filename> file.  In other
          words, if a <filename>server-Standard</filename> section is defined
          in <filename>&lt;etc&gt;/mdm/custom.conf</filename>, then that
          will be used and the section in the
          <filename>&lt;share&gt;/mdm/defaults.conf</filename> file will be
          ignored.
        </para>

        <variablelist>
          <title>[server-Standard]</title>

          <varlistentry>
            <term>name</term>
            <listitem>
              <synopsis>name=Standard server</synopsis>
              <para>
                The name that will be displayed to the user.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>command</term>
            <listitem>
              <synopsis>command=/path/to/X</synopsis>
              <para>
                The command to execute, with full path to the binary of the X
                server, and any extra arguments needed.  Normally it is not
                necessary to add a <filename>-nolisten tcp</filename> argument
                since the addition of this argument is controlled by the
                <filename>DisallowTCP</filename> MDM configuration option.
              </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 MDM should run the login window on this server
                and allow a user to log in.  If set to false, then MDM will
                just run this server and wait for it to terminate.  This can be
                useful to run an X terminal using MDM.  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 MDM and, for example, soft restarts won't work.
                This is because MDM 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 MDM 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>

          <varlistentry>
            <term>priority</term>
            <listitem>
              <synopsis>priority=0</synopsis>
              <para>
                Indicates that the X server should be started at a
                different process priority.  Values can be any integer
                value accepted by the setpriority C library function
                (normally between -20 and 20) with 0 being the default.
                For highly interactive applications, -5 yields good
                responsiveness.  The default value is 0 and the 
                setpriority function is not called if the value is 0.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="attacheddisplayconfig">
        <title>Attached DISPLAY Configuration</title>

        <para>
          The attached (also known as local or static) display configuration
          specifies what displays should be always managed by MDM.  MDM will
          restart the X server on the display if it dies, for example.  There
          may be as many attached displays that are managed as you wish.
          Typically each display is associated with a real display.  On a
          typical single-display machine this section would only contain one
          key <filename>0</filename> that corresponds to DISPLAY
          <filename>:0</filename>.
        </para>

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

        <variablelist>
          <title>[servers]</title>
          
          <varlistentry>
            <term>&lt;display number&gt;</term>
            <listitem>
              <synopsis>0=Standard [device=/dev/foo]</synopsis>

              <para>
                The key cooresponds to the DISPLAY to be managed, so that
                key <filename>0</filename> cooresponds to DISPLAY
                <filename>:0</filename>.  On a multi-display machine you
                can configure MDM to manage a login program on other displays
                by adding additional keys.  For example, adding key
                <filename>1</filename> would cause MDM to manage DISPLAY
                <filename>:1</filename>.
              </para>

              <para>
                The first word of the value corresponds to a X server
                definition in the &quot;X Server Definitions&quot; section
                of the configuration file.  For example, the following entry
                means that DISPLAY <filename>:0</filename> will start an X
                server as defined in the
                <filename>[server-Standard]</filename> section:
              </para>

<screen>
[servers]
0=Standard
</screen>

              <para>
                The first word of the value can also be set to the string
                &quot;inactive&quot; to indicate that this DISPLAY should not 
                be managed.  This can be used in the MDM Custom Configuration
                File to turn off a DISPLAY that is defined in the MDM System
                Defaults Configuration File.
              </para>

              <para>
                The optional device argument is used to specify the device that
                is associated with the DISPLAY.  When using Virtual Terminals
                (VT), this value is ignored and MDM will use the correct
                device name associated with the VT.  If not using VT, then MDM
                will use the value specified by this optional argument.  If
                the device argument is not defined, then MDM will use the
                default setting for attached displays defined in the
                <filename>UtmpLineAttached</filename> configuration section.
                For the main display (typically DISPLAY
                <filename>:0</filename>), <filename>/dev/console</filename> is
                a reasonable value.  For other displays it is probably best
                to not include this argument unless you know the specific
                device associated with the DISPLAY.  The device value can
                contain &quot;%d&quot; which is translated to the DISPLAY value
                or &quot;%h&quot; which is translated to the hostname.
              </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 MDM
        behaves.  MDM is picky about the file ownership and permissions of 
        the user files it will access, and will ignore files if they are not
        owned by the user or files that have group/world write permission.
        It will also ignore the user if the user's $HOME directory is not
        owned by the user or if the user's $HOME directory has group/world
        write permission.  files must also be smaller than the
        <filename>UserMaxFile</filename> value as defined in the MDM
        configuration.  If it seems that MDM is not properly accessing 
        user configuration settings, the problem is most likely 
        caused by one of these checks failing.
      </para>

      <para>
        First there is the <filename>~/.dmrc</filename> file.  In
        theory this file should be shared between MDM and KDM, so users only
        have to configure things once.  This is a standard
        <filename>.ini</filename> style configuration file.  It has one section
        called <filename>[Desktop]</filename> which has two keys:
        <filename>Session</filename> and <filename>Language</filename>.
      </para>

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

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

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

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

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

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

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

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

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

      <para>
        The <command>mdmflexiserver</command> command can be used to start
        new flexible (on demand) displays if your system supports virtual
        terminals.  This command will normally lock the current session with a
        screensaver so that the user can safely walk away from the computer and
        let someone else log in.  If more that two flexible displays have 
        started <command>mdmflexiserver</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>mdmflexiserver --help</command> to get a listing of possible
        options.  
      </para>
    </sect2>

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

      <para>
        MDM also provides a FIFO called <filename>.mdmfifo</filename> in the
        <filename>ServAuthDir</filename> directory
        (usually <filename>&lt;var&gt;/mdm/.mdmfifo</filename>).  You must be
        root to use this protocol, and it is mostly used for internal MDM
        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 MDM 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 MDM source tree in the file
        <filename>daemon/mdm.h</filename>.  Look for the defines starting with
        <filename>MDM_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>
        MDM provides a unix domain socket for communication at
        <filename>/tmp/.mdm_socket</filename>.  Using this you can check if
        MDM is running, the version of the daemon, the current displays that
        are running and who is logged in on them, and if MDM supports it on
        your operating system, also the virtual terminals of all the console
        logins.  The <command>mdmflexiserver</command> command uses this
        protocol, for example, to launch flexible (on-demand) displays.
      </para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

               Starting with version 2.13.0.0, all MDM 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

               MDM also supports the following Psuedokeys:

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

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

                Supported keys for previous versions of MDM:

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

  <!-- ============= MDM Commands ============================= -->

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

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

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

      <sect3 id="mdmrecoverycommandline">
          <title><command>mdm-recovery</command></title>
          <para><command>mdm-recovery</command> gives MDM a safe configuration. Its purpose is to prevent most common issues from happening and helping the user successfully log in. Launch this command if you are unable to log in.</para>
      </sect3>     

      <sect3 id="mdmthemeemulatorcommandline">
          <title><command>mdm-theme-emulator</command></title>
          <para><command>mdm-theme-emulator</command> is an emulator for HTML theme artists. It is able to open HTML themes and emulate MDM to a certain extent.</para>
      </sect3>


      <sect3 id="mdmflexiservercommandline">
          <title><command>mdmflexiserver</command></title>
          <para><command>mdmflexiserver</command> locks the session and invokes a greeter (i.e. a login screen). It is the command used by the screensaver to switch users. If a greeter is already running, mdmflexiserver switches to it. Otherwise it asks MDM to start a new one.</para>

          <para><command>mdmflexiserver</command> can also be used with the -c argument to launch a command on the MDM daemon.</para>

          <para>For instance <command>mdmflexiserver -c "GET_CONFIG daemon/Greeter"</command> returns the value of the active greeter.</para>

          <para>And <command>mdmflexiserver -c "ATTACHED_SERVERS"</command> returns a list of active MDM servers (i.e. sessions and greeters).</para>
      </sect3>     

    </sect2>

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

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

      <sect3 id="mdmcommandline">
        <title><command>mdm</command></title>

        <variablelist>
          <title>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 MDM does not fork into the
                background when run. You can also use a single-dash version,
                &quot;-nodaemon&quot; for compatibility with other display
                managers.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--no-console</term>
            <listitem>
              <para>
                Tell the daemon that it should not run anything on the console.
                This means that none of the attached servers from the
                <filename>[servers]</filename> section will be started, 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 MDM daemon.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>--wait-for-go</term>
            <listitem>
              <para>
                If started with this option, mdm will init, but only start the
                first attached 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 MDM will
                then continue.  This functionality was added in version
                2.5.90.0.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="mdmsetupcommandline">
        <title><command>mdmsetup</command></title>

        <para>
         <command>mdmsetup</command> runs a graphical application for modifying
         the MDM configuration file.
        </para>
      </sect3>
      
    </sect2>

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

      <para>
        The MDM package provides the following different commands in
        <filename>/usr/lib/mdm/</filename> intended to be used by the mdm
        daemon process.
      </para>

      <sect3 id="mdmgreeterlogincommandline">
        <title><command>mdmlogin</command>, <command>mdmgreeter</command> and <command>mdmwebkit</command></title>

        <para>
          The <command>mdmlogin</command>, <command>mdmgreeter</command> and <command>mdmwebkit</command>
          are three different login applications which can be used by MDM. <command>mdmlogin</command> is a simple GTK login screen, while <command>mdmgreeter</command> and <command>mdmwebkit</command> are respectively themed with GDM and HTML themes. These
          applications are normally executed by the MDM daemon.
        </para>
      </sect3>

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

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

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

  <sect1 id="thememanual">
    <title>GDM Themes</title>

    <para>
      This section describes the creation of GDM themes. For examples of themes, visit 
      <ulink type="http" url="http://gnome-look.org">
      gnome-look.org</ulink> and select "GDM Themes".
    </para>

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

      <para>
        GDM Themes are located in <filename>/usr/share/mdm/themes</filename>. They contain a file called
        <filename>GdmGreeterTheme.desktop</filename> which has a similar format
        to other .desktop files and looks like this:
      </para>

<screen>
[GdmGreeterTheme]
Encoding=UTF-8
Greeter=configuration.xml
Name=Mytheme
Description=My Theme
Author=My name
Copyright=GPL
Screenshot=screenshot.jpg
</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. The Greeter field points to an XML file that contains the
        structure of the theme itself.
      </para>   
     
    </sect2>

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

      <sect3 id="greetertag">
        <title>greeter tag</title>

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

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

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

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

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

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

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

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

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

        <para>
          The &quot;toplevel&quot; node is really just like a fixed node.
        </para>
      </sect3>

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

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

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

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

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

          <varlistentry>
            <term>list</term>
            <listitem>
              <para>
                 A face browser widget.  Only useful if the face browser is
                 enabled via the configuration.
              </para>
            </listitem>
          </varlistentry>

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

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

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

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

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

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

        <para>
          List items by default display as lists, but the
          combo=&quot;true&quot; attribute can be used to specify combo box
          style.  Some predefined
          lists may be included in a theme by using the following id values.
          Customized lists may also be defined, which are explained below.
        </para>

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

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

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

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

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

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

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

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

          <varlistentry>
            <term>pam-error</term>
            <listitem>
              <para>
                Label that displayst PAM/MDM error messages.  Such as when user
                can't log in.
              </para>
            </listitem>
          </varlistentry>

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

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

          <varlistentry>
            <term>timed-label</term>
            <listitem>
              <para>
                Label that displays timed login information.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>
          Rectangles can have id values as follows:
        </para>

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

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

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

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

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

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

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

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

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

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

        <para>
          By default, the MDM login screen will disappear after authentication.
          This can result in flicker between the login screen and the session.
          The &quot;background&quot; property allows users to specify what 
          elements of the theme are the background image.  When used, this
          will cause MDM to remove all non-background items from the display
          and render the remaining &quot;background&quot; items to the root
          window.  This can be used to create a smooth transition between the
          login screen and the session.  For example, if the GDM theme and the
          session use the same background, then this will make the background
          apear seamless.
        </para>
          
        <para>
          Item nodes may specify a &quot;background&quot; property which can be
          set to &quot;true&quot; or &quot;false&quot; (not setting this
          property is equivalent to &quot;false&quot;), as follows:
        </para>

<screen>
&lt;item type=&quot;rect&quot; background=&quot;true&quot;&gt;
    &lt;normal file="background.svg"/&gt;
    &lt;pos x=&quot;0&quot; y=&quot;0&quot; width=&quot;100%&quot; height=&quot;-75&quot;/&gt;
&lt;/item&gt;
</screen>

        <para>
          If no item node has &quot;background&quot; property set, then the
          background is not modified when greeter exits.
        </para>

        <para>
          To use a different background for login transition than the one 
          used for login, the theme should specify two item nodes (which
          could contain pixmaps or svg images, for example).  The item
          which corresponds to the greeter background should not have the
          &quot;background&quot; property while the item which corresponds
          to the transition background should have the &quot;background&quot;
          property.  For instance :
        </para>
<screen>
&lt;?xml version="1.0" encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE greeter SYSTEM &quot;greeter.dtd&quot;&gt;
 &lt;greeter&gt;

  &lt;item type=&quot;rect&quot; background=&quot;true&quot;&gt;
    &lt;normal file="background_for_login.svg"/&gt;
    &lt;pos x=&quot;0&quot; y=&quot;0&quot; width=&quot;100%&quot; height=&quot;100%&quot;/&gt;
  &lt;/item&gt;
  &lt;item type=&quot;rect&quot;&gt;
    &lt;normal file="background_for_greeter.svg"/&gt;
    &lt;pos x=&quot;0&quot; y=&quot;0&quot; width=&quot;100%&quot; height=&quot;100%&quot;/&gt;
  &lt;/item&gt;
[...]
&lt;/greeter&gt;
</screen>
      </sect3>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        <para>
          <filename>chooser</filename>, if ChooserButton is set to
          &quot;true&quot; in the MDM configuration.
        </para>
        <para>
          <filename>config</filename>, if ConfigAvailable is set to
          &quot;true&quot; in the MDM configuration.
        </para>
        <para>
          <filename>custom_cmd[0-9]</filename>, if <filename>n-th</filename>
          CustomCommand is specified in the MDM configuration.
        </para>
        <para>
          <filename>halt</filename>, if HaltDaemon is specified in
          the MDM configuration.
        </para>
        <para>
          <filename>reboot</filename>, if RebootCommand is specified in
          the MDM configuration.
        </para>
        <para>
          <filename>suspend</filename>, if SuspendCommand is specified in
          the MDM configuration.
        </para>
        <para>
          <filename>system</filename>, if SystemMenu is specified in
          the MDM configuration.
        </para>
        <para>
          <filename>timed</filename>, if TimedLoginEnabled is set to
          &quot;true&quot; in the MDM configuration.
        </para>

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

        <para>
          Alternatively, you can specify a &quot;min-screen-width&quot; or
          &quot;min-screen-height&quot; value to indicate that certain
          items should only be displayed if the screen resolution is the
          at least the given required size.
        </para>

        <para>
          For example:
<screen>
&lt;show min-screen-height=&quot;768&quot;/&gt;
</screen>
        </para>

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

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

        <para>
          Depending on the item type (except for userlist - refer to Color node
          below), it can specify its color, font, or image via the following
          tags:
        </para>

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

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

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

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

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

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

      </sect3>

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

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

        <para>
<screen>
&lt;color iconcolor=&quot;#dddddd&quot; labelcolor=&quot;#ffffff&quot;/&gt;
</screen>
        </para>
      </sect3>

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

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

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

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

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

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

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

        <para>
          <filename>cancel</filename>, _(&quot;_Cancel&quot;
        </para>
        <para>
          <filename>caps-lock-warning</filename>,
          _(&quot;Caps Lock is on.&quot; 
        </para>                
        <para>
          <filename>disconnect</filename>, _(&quot;D_isconnect&quot;
        </para>
        <para>
          <filename>halt</filename>, _(&quot;Shut _Down&quot;
        </para>
        <para>
          <filename>language</filename>, _(&quot;_Language&quot;
        </para>
        <para>
          <filename>ok</filename>, _(&quot;_OK&quot;
        </para>
        <para>
          <filename>options</filename>, _(&quot;_Options&quot;
        </para>
        <para>
          <filename>quit</filename>, _(&quot;_Quit&quot;
        </para>
        <para>
          <filename>reboot</filename>, _(&quot;_Restart&quot;
        </para>
        <para>
          <filename>session</filename>, _(&quot;_Session&quot;
        </para>
        <para>
          <filename>startagain</filename>, _(&quot;_Start Again&quot;
        </para>
        <para>
          <filename>suspend</filename>, _(&quot;Sus_pend&quot;
        </para>
        <para>
          <filename>system</filename>, _(&quot;_Actions&quot;
          (Formerly &quot;S_ystem&quot;
        </para>
        <para>
          <filename>timed-label</filename>,
          _(&quot;User %u will login in %t&quot;
        </para>
        <para>
          <filename>username-label</filename>, _(&quot;Username:&quot;
        </para>
        <para>
          <filename>welcome-label</filename>, _(&quot;Welcome to %n&quot;
        </para>

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

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

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

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

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

        <para>
          The file is created in INI format.  The group value
          is &quot;GreeterInfo&quot;, and the &quot;custom-config&quot; key
          will specify the id of the chosen listitem.  For example, if the user
          chooses &quot;Foo&quot; (which has an id value of &quot;foo&quot;,
          then <filename>&lt;var&gt;/lib/mdm/:0.GreeterInfo</filename> will
          contain:
<screen>
[GreeterInfo]
custom-config=foo
</screen>
        </para>        
      </sect3>
    </sect2>
  </sect1>

  

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

    <para>
      This section discusses helpful tips for getting MDM working.
    </para>

    <para>
      If MDM is failing to work properly, it is always a good idea to include
      debug information.  Use the <command>mdmsetup</command> command to turn
      on debug (&quot;Log debug information to /var/log/syslog&quot; in the 
      &quot;Options&quot; tab), reboot and then use MDM to the point where it fails, and
      include the MDM output sent to your system log
      (<filename>&lt;var&gt;/log/syslog</filename>). Since the system log can be large, please only include the MDM
      debug information and do not sent the entire file.
    </para>    

    <para>
       If MDM fails to start or you can't log in, reset MDM to its default configuration by using the command <command>mdm-recovery</command>.
       This usually solves the most common issues or the ones related to configuration or a faulty theme.
    </para>

    <para>
       If you face an issue with one particular greeter, try to run that greeter on its own with the command 
       <command>DOING_MDM_DEVELOPMENT=1 /usr/lib/mdm/mdmlogin</command> (for the GTK greeter),
       <command>DOING_MDM_DEVELOPMENT=1 /usr/lib/mdm/mdmgreeter</command> (for the GDM greeter) or
       <command>DOING_MDM_DEVELOPMENT=1 /usr/lib/mdm/mdmwebkit</command> (for the HTML greeter).
       Any error messages echoed to the terminal will likely highlight the problem.  Also,
       turning on debug and checking the output sent to the system log will often highlight the problem.
    </para>

    <para>
       Also make sure that the <filename>/tmp</filename> directory has
       reasonable ownership and permissions, and that the machine's file
       system is not full.  These problems will cause MDM to fail to start.
    </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:
-->