gdm.xml 302 KB
Newer Older
1
<?xml version="1.0"?>
2
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
    <!ENTITY legal SYSTEM "legal.xml">
5 6
    <!ENTITY version "2.18.0"> 
    <!ENTITY date "03/12/2007"> 
7 8
]>

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

13 14 15
    <revhistory>
      <revision>
        <revnumber>0.0</revnumber>
16
        <date>2007-01</date>
17 18 19
      </revision>
    </revhistory>

20 21
    <abstract role="description">
      <para>
22
        GDM is the GNOME Display Manager, a graphical login program.
23 24 25
      </para>
    </abstract>

26 27
    <authorgroup>
      <author>
28 29
        <firstname>Martin</firstname><othername>K.</othername>
           <surname>Petersen</surname>
30 31 32 33 34 35 36 37 38 39
        <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>
40
      <author role="maintainer">
41 42 43 44 45
        <firstname>Brian</firstname><surname>Cameron</surname>
        <affiliation>
          <address><email>Brian.Cameron@Sun.COM</email></address>
        </affiliation>
      </author>
46 47 48 49 50 51
      <author>
        <firstname>Bill</firstname><surname>Haneman</surname>
        <affiliation>
          <address><email>Bill.Haneman@Sun.COM</email></address>
        </affiliation>
      </author>
52 53
    </authorgroup>
    <copyright>
54
      <year>1998</year><year>1999</year><holder>Martin K. Petersen</holder>
55 56
    </copyright>
    <copyright>
57 58
      <year>2001</year><year>2003</year><year>2004</year>
        <holder>George Lebl</holder>
59
    </copyright>
60 61 62 63
    <copyright>
      <year>2003</year> <holder>Red Hat, Inc.</holder>
    </copyright>
    <copyright>
64
      <year>2003</year><year>2004</year><holder>Sun Microsystems, Inc.</holder>
65
    </copyright>
66

67 68 69
    &legal;

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

Jiri (George) Lebl's avatar
Jiri (George) Lebl committed
75 76
  <sect1 id="preface">
    <title>Terms and Conventions Used in This Manual</title>
77

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

83 84 85 86 87 88 89 90 91 92
    <para>
      Chooser - A program used to select a remote host for managing a
      display remotely on the local display (<command>gdmchooser</command>).
    </para>

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

93
    <para>
94 95
      GDM - Gnome Display Manager. Used to describe the software package as a
      whole.  Sometimes also referred to as GDM2.
96 97 98
    </para>

    <para>
99
      gdm - The Gnome Display Manager daemon (<command>gdm</command>).
100 101 102
    </para>

    <para>
103 104
      Greeter - The graphical login window (<command>gdmlogin</command> or
      <command>gdmgreeter</command>).
105 106 107
    </para>

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

    <para>
112
      PAM - Pluggable Authentication Mechanism
113 114 115
    </para>

    <para>
116 117
      Themed Greeter - The themable login window (
      <command>gdmgreeter</command>).
118 119 120
    </para>

    <para>
121
      XDMCP - X Display Manage Protocol
122 123 124
    </para>

    <para>
125 126
      Paths that start with a word in angle brackets are relative to the
      installation prefix. I.e. <filename>&lt;share&gt;/pixmaps/</filename>
127
      refers to <filename>&lt;share&gt;/pixmaps</filename> if GDM was configured
128
      with <command>--prefix=/usr</command>.  Normally also note that
129
      GDM is installed with <command>--sysconfigdir=&lt;etc&gt;/X11</command>,
130 131
      meaning any path to which we refer to as
      <filename>&lt;etc&gt;/gdm/PreSession</filename> usually means
132
      <filename>&lt;etc/X11&gt;/gdm/PreSession</filename>.  Note that for
133 134
      interoperability it is recommended that you use a --prefix of
      <filename>/usr</filename> and a --sysconfdir of
135
      <filename>&lt;etc&gt;/X11</filename>.
136
    </para>
Jiri (George) Lebl's avatar
Jiri (George) Lebl committed
137
  </sect1>
138

139
  <sect1 id="overview">
140 141
    <title>Overview</title>

142
    <sect2 id="introduction">
143
      <title>
144
        Introduction
145 146 147
      </title>

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

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

166 167 168 169 170 171
    <sect2 id="stability">
      <title>
        Interface Stability
      </title>

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

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

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

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

208
    <sect2 id="daemonov">
209 210
      <title>The GDM Daemon</title>
      
211
      <para>
212 213 214 215 216 217 218 219
        The GDM daemon is responsible for managing displays on the system.
        This includes authenticating users, starting the user session, and
        terminating the user session.  GDM is configurable and the ways it can
        be configured are described in the &quot;Configuring GDM&quot; section
        of this document.  The <filename>Init</filename>,
        <filename>PostLogin</filename>, <filename>PreSession</filename>, 
        and <filename>PostSession</filename> scripts discussed below are 
        discussed in this &quot;Configuring GDM section&quot;.
220 221 222
      </para>

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

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

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

273 274 275 276 277 278
      <para> 
        GDM, by default, will use Pluggable Authentication Modules (PAM) for
        authentication, but can also support regular crypt and shadow passwords
        on legacy systems.  After authenticating a user, the daemon runs the
        <filename>PostLogin</filename> script as root, and forks a slave
        process to start the requested session.  This slave process runs the
279
        <filename>PreSession</filename> script as root, sets up the user's
280 281 282 283 284 285
        environment, and starts the requested session.  GDM keeps track of the
        user's default session and language in the user's
        <filename>~/.dmrc</filename> and will use these defaults if the user
        did not pick a session or language in the login GUI.  On Solaris, GDM
        (since version 2.8.0.3) uses the SDTLOGIN interface after user
        authentication to tell the X server to be restarted as the user instead
286
        of as root for added security.  When the user's session exits, the GDM
287
        daemon will run the <filename>PostSession</filename> script as root.
288
      </para>
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303

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

      <para>
        For those looking at the code, the gdm_verify_user function in 
        <filename>daemon/verify-pam.c</filename> is used for normal login
        and the gdm_verify_setup_user function is used for automatic login.
Brian Cameron's avatar
Brian Cameron committed
304
      </para>
305 306 307 308 309 310
    </sect2>

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

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

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

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

347 348 349 350 351 352 353
      <para>
        The last display type is the XDMCP remote displays which are described
        in the next section.  Remote hosts can connect to GDM and present the
        login screen if this is enabled.  Some things are different for
        remote sessions.  For example, the Actions menu which allows you to
        shut down, restart, suspend, or configure GDM are not shown.
      </para>
354 355 356 357 358 359 360 361

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

    <sect2 id="xdmcp">
365
      <title>
366
        XDMCP
367 368 369
      </title>

      <para>
370 371 372 373 374 375 376 377 378 379 380 381 382 383
        The GDM daemon can be configured to listen for and manage X Display
        Manage Protocol (XDMCP) requests from remote displays.  By default
        XDMCP support is turned off, but can be enabled if desired.  If GDM is
        built with TCP Wrapper support, then the daemon will only grant access
        to hosts specified in the GDM service section in the TCP Wrappers
        configuration file.
      </para>

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

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

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

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

407 408 409 410 411 412 413 414 415 416 417 418 419 420
    <sect2 id="secureremote">
      <title>
        Securing Remote Connection Through SSH
      </title>
      <para>
        As explained in the &quot;Security&quot; section, XDMCP does not use
        any kind of encryption and as such is inherently insecure.  As XDMCP
        uses UDP as a network transport layer, it is not possible to simply
        secure it through an SSH tunnel.
      </para>

      <para>
        To remedy this problem, gdm can be configured at compilation-time with
        the option --enable-secureremote, in which case gdm proposes as a
421 422 423 424 425
        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.
426 427 428 429 430 431 432 433
      </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>

434 435
    <sect2 id="gtkgreeter">
      <title>The GTK+ Greeter</title>
436 437

      <para>
438 439 440
        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.
441 442
        This greeter has full accessibility support, and should be used
        by users with accessibility needs.
443 444
      </para>

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

455
      <para>
456 457
        The menu bar in the top of the greeter enables the user to select the
        requested session type/desktop environment, select an appropriate
458
        locale/language, halt/restart/suspend the computer, configure GDM
459 460
        (given the user knows the root password), change the GTK+ theme, or
        start an XDMCP chooser.
461
      </para>
462 463

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

472 473
    <sect2 id="themedgreeter">
      <title>The Themed Greeter</title>
474 475

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

485
      <para>
486 487 488 489 490
        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,
491
        halt/restart/suspend the computer, configure GDM (given the user
492
        knows the root password), or start an XDMCP chooser.
493 494 495
      </para>

      <para>
496 497
        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
498
        you wish to do some action allowed by the GDM configuration.
499
      </para>
500
    </sect2>
501

502 503
    <sect2 id="facebrowser">
      <title>The GDM Face Browser</title>
504 505

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

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

524
      <para>
525 526
        The icons used by GDM can be installed globally by the sysadmin or can
        be located in the users' home directories.  If installed globally
527
        they should be in the <filename>&lt;share&gt;/pixmaps/faces/</filename>
528
        directory (though this can be configured with the
529 530 531 532
        <filename>GlobalFaceDir</filename> configuration option) and the
        filename should be the name of the user, optionally with a
        <filename>.png</filename> appended.  Face icons placed in the global
        face directory must be readable to the GDM user.  However, the daemon,
533 534
        proxies user pictures to the greeter and thus those do not have be be
        readable by the &quot;gdm&quot; user, but root.
535
      </para>
536

537
      <para>
538 539 540 541 542 543 544 545 546
        Users may run the <command>gdmphotosetup</command> command to 
        configure the image to use for their userid.  This program properly
        scales the file down if it is larger than the
        <filename>MaxIconWidth</filename> or 
        <filename>MaxIconHeight</filename> configuration options and places the
        icon in a file called <filename>~/.face</filename>.  Although
        <command>gdmphotosetup</command> scales user images automatically,
        this does not guarantee that user images are properly scaled since
        a user may create their <filename>~/.face</filename> file by hand.
547
      </para>
548
        
549
      <para>
550 551 552
        GDM will first look for the user's face image in
        <filename>~/.face</filename>.  If not found, it will try 
        <filename>~/.face.icon</filename>.  If still not found, it will
553
        use the value defined for &quot;face/picture=&quot; in the 
554 555 556 557
        <filename>~/.gnome2/gdm</filename> file.  Lastly, it will try
        <filename>~/.gnome2/photo</filename> and 
        <filename>~/.gnome/photo</filename> which are deprecated and
        supported for backwards compatibility.
558
      </para>
559

560
      <para>
561 562
        If a user has no defined face image, GDM will use the
        &quot;stock_person&quot; icon defined in the current GTK+ theme.  If no
563
        such image is defined, it will fallback to the image specified in the
564
        <filename>DefaultFace</filename> configuration option, normally
565
        <filename>&lt;share&gt;/pixmaps/nobody.png</filename>.
566 567
      </para>
      
568
      <para>
569
        Please note that loading and scaling face icons located in user home
570
        directories can be a very time-consuming task.  Since it not 
571 572 573 574
        practical to load images over NIS or NFS, GDM does not attempt to
        load face images from remote home directories.  Furthermore, GDM will
        give up loading face images after 5 seconds of activity and will
        only display the users whose pictures it has gotten so far.  The
575 576 577 578
        <filename>Include</filename> configuration option can be used to
        specify a set of users who should appear on the face browser.  As
        long as the users to include is of a reasonable size, there should
        not be a problem with GDM being unable to access the face images.
579
        To work around such problems, it is recommended to place face images
580 581
        in the directory specified by the <filename>GlobalFaceDir</filename>
        configuration option.
582 583 584 585 586 587 588 589 590 591
      </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.
592 593
        Any user listed in the <filename>Exclude</filename> option and users
        whose UID's is lower than <filename>MinimalUID</filename> will be
594
        filtered out regardless of the <filename>IncludeAll</filename>
595
        setting.  <filename>IncludeAll</filename> is not recommended
596 597 598
        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..
599
      </para>
600

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

609 610 611 612
    <sect2 id="logging">
      <title>Logging</title>

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

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

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

643
      <para>
644 645 646 647 648 649
        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
650
        GDM message would be confusing and redundant.
651 652
      </para>

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

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

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

688
      <para>
689 690 691 692
        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.
693
      </para>
694 695 696 697 698 699 700
    </sect2>

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

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

711 712 713 714 715
      <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>
716
        configuration setting (<filename>/tmp</filename> by default).
717 718 719 720 721 722 723 724 725 726
      </para>

      <para>
        Finally, the sysadmin can specify the maximum file size GDM should
        accept, and, if the face browser is enabled, a tunable maximum icon
        size is also enforced.  On large systems it is still advised to turn
        off the face browser for performance reasons.  Looking up icons in
        home directories, scaling and rendering face icons can take a long
        time.
      </para>
727
    </sect2>
728 729 730 731 732 733 734 735 736 737 738 739 740

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

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

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

760
  <sect1 id="security">
761
    <title>Security</title>
762

763 764 765 766
    <sect2 id="PAM">
      <title>
        PAM
      </title>
767

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

      <para>
775 776 777 778
        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.
779 780 781
      </para>

      <para>
Brian Cameron's avatar
Brian Cameron committed
782
        Some GDM features (like turning on automatic login) may require that
783 784 785 786 787 788
        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.
789 790 791
      </para>

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

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

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

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

818
      <para>
819 820
        The GDM daemon normally runs as root, as does the slave.  However GDM
        should also have a dedicated user id and a group id which it uses for
821
        its graphical interfaces such as <command>gdmgreeter</command> and
822 823
        <command>gdmlogin</command>.  These are configured via the
        <filename>User</filename> and <filename>Group</filename>
824 825 826
        configuration options in the GDM configuration files.  The user and
        group should be created before running &quot;make install&quot;.  By
        default GDM assumes the user and the group are called &quot;gdm&quot;. 
827 828 829
      </para>

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

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

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

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

869 870 871
    <sect2 id="xauth">
      <title>X Server Authentication Scheme</title>
 
872
      <para>
873
        The X server authorization directory (the
874 875 876 877 878 879 880 881
        <filename>ServAuthDir</filename>) is used for a host of random
        internal data in addition to the X server authorization files, and the
        naming is really a relic of history.  GDM daemon enforces this
        directory to be owned by <filename>root.gdm</filename> with the
        permissions of 1770.  This way, only root and the GDM group have write
        access to this directory, but the GDM group cannot remove the root
        owned files from this directory, such as the X server authorization
        files.
882 883 884
      </para>

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

      <para>
894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953
        GDM only supports the MIT-MAGIC-COOKIE-1 X server authentication
        scheme.  Normally little is gained from the other schemes, and no
        effort has been made to implement them so far.  Be especially
        careful about using XDMCP because the X server authentication cookie
        goes over the wire as clear text.  If snooping is possible, then an
        attacker could simply snoop your authentication password as you log in,
        regardless of the authentication scheme being used.  If snooping is
        possible and undesirable, then you should use ssh for tunneling an X
        connection rather then using XDMCP.  You could think of XDMCP as a sort
        of graphical telnet, having the same security issues.
      </para>

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

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

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

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

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

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

      <para>
        Note that NFS traffic really goes &quot;over the wire&quot; and thus
        can be snooped.  When accessing the user's X authorization file
954 955 956 957 958 959
        (<filename>~/.Xauthority</filename>), GDM will try to open the file
        for reading as root.  If it fails, GDM will conclude that it is on an
        NFS mount and it will automatically use
        <filename>UserAuthFBDir</filename>, which by default is set to
        <filename>/tmp</filename>.  This behavior can be changed by setting the
        <filename>NeverPlaceCookiesOnNFS</filename> in the
960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987
        <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>
988 989

      <para>
990 991 992
        To workaround the inherent insecurity of XDMCP, gdm proposes a default
        built-in session that uses SSH to encrypt the remote connection.  See
        the section &quot;Securing remote connection through SSH&quot; above.
993
      </para>
994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007
    </sect2>

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

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

      <para>
        You should use the daemon name <command>gdm</command> in the
        <filename>&lt;etc&gt;/hosts.allow</filename> and
1008
        <filename>&lt;etc&gt;/hosts.deny</filename> files.  For example to 
1009 1010 1011
        deny computers from <filename>.evil.domain</filename> from logging in,
        then add
      </para>
1012 1013 1014
<screen>
gdm: .evil.domain
</screen>
1015 1016 1017 1018
      <para>
        to <filename>&lt;etc&gt;/hosts.deny</filename>.  You may also need
        to add
      </para>
1019 1020 1021
<screen>
gdm: .your.domain
</screen>
1022 1023 1024 1025 1026
      <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.
1027 1028
      </para>
    </sect2>
1029
  </sect1>
1030

1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070
  <sect1 id="consolekit">
    <title>Support for ConsoleKit</title>

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

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

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

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

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

  </sect1>

1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332
  <sect1 id="gdmsetupusage">
    <title>Using gdmsetup To Configure GDM</title>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1333 1334
  <sect1 id="configuration">
    <title>Configuration</title>
1335 1336

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

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

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

    <para>
      If you want to change configuration by hand, edit the
1376 1377 1378 1379 1380
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> file and make
      sure the keyname=value pair you want is included in the appropriate
      section.  For example, to change the &quot;Greeter&quot; key in the
      &quot;daemon&quot; section, make sure the daemon section of the
      <filename>&lt;etc&gt;/gdm/custom.conf</filename> file has the value
1381
      like in this example.  
1382 1383 1384 1385 1386 1387 1388
    </para>

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

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

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

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

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

    <para>
1434
      The other GDM configuration files are located, by default, in the
1435
      <filename>&lt;etc&gt;/gdm/</filename> folder or its subdirectories.
1436 1437 1438
      However, the location of all configuration files are defined in 
      the GDM configuration files, so the sysadmin may choose to locate these
      files in any location. 
1439 1440 1441 1442 1443 1444
    </para>

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

1445
<screen>
1446 1447 1448
locale.alias
Xsession
XKeepsCrashing
1449 1450 1451 1452 1453
modules/
Init/
PostLogin/
PreSession/
PostSession/
1454
</screen>
1455

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

    <para> 
      <filename>Xsession</filename> is a script which sets up a user session
1466
      and then executes the user's choice of session.  Note that the session
1467 1468 1469 1470 1471 1472
      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.
1473 1474 1475 1476
    </para>

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

1483 1484
    <para>
      Accessibility modules are configured in the <filename>modules/</filename>
1485 1486 1487 1488 1489
      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.
1490 1491
    </para>

1492
    <para>
1493 1494
      Files describing available GDM session follow the freedesktop.org
      desktop file specification and are <filename>.desktop</filename>-style
1495 1496
      files are installed to <filename>&lt;etc&gt;/X11/sessions/</filename>.
      This directory is also read by the KDE desktop manager (KDM) for common
1497
      configuration.  Next the directory
1498
      <filename>&lt;share&gt;/gdm/BuiltInSessions/</filename> is read for
1499 1500
      GDM specific built-in sessions (KDM hardcodes these at time of
      this writing).  Lastly the default setup will also read
1501
      <filename>&lt;share&gt;/xsessions/</filename> (which should be
1502
      <filename>&lt;share&gt;/xsessions/</filename> if you really wish to
1503
      cooperate with KDM) where desktop packages can install their session
1504 1505
      files.  The directories under the <filename>&lt;etc&gt;</filename> should
      be reserved for configuration.  The desktop file specification approach
1506 1507 1508
      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
1509 1510
      changing the paths.  It used to be that GDM stored its built in
      sessions in <filename>&lt;etc&gt;/dm/Sessions/</filename> but this is
1511 1512
      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.
1513 1514 1515 1516
    </para>

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

1523
    <sect2 id="scriptdirs">
1524 1525 1526
      <title>The Script Directories</title>
      
      <para>
1527 1528 1529
        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.
1530 1531 1532
      </para>

      <para>
1533 1534 1535 1536 1537 1538 1539 1540 1541
        When the X server has been successfully started, GDM will try to run
        the script called <filename>Init/&lt;displayname&gt;</filename>. I.e.
        <filename>Init/:0</filename> for the first local display.  If this file
        is not found, GDM will attempt to to run
        <filename>Init/&lt;hostname&gt;</filename>. I.e.
        <filename>Init/somehost</filename>.
        If this still is not found, GDM will try
        <filename>Init/XDMCP</filename> for all XDMCP logins or
        <filename>Init/Flexi</filename> for all on demand flexible
1542
        displays.  If none of the above were found, GDM will run
1543 1544
        <filename>Init/Default</filename>. The script will be run as root and
        GDM blocks until it terminates. Use the <filename>Init/*</filename>
1545
        script for applications that are supposed to run alongside with the GDM
1546
        login window. xconsole for instance.  Commands to set the background
1547
        etc. go in this file too.
1548 1549 1550
      </para>

      <para> 
1551 1552
        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
1553 1554
        controlled with the <filename>KillInitClients</filename> configuration
        option.
1555 1556 1557
      </para>

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

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

      <para>
1587 1588 1589 1590 1591 1592
        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
1593
        <filename>&lt;etc&gt;/X11/sessions/:&lt;etc&gt;/dm/Sessions:/usr/share/xsessions/</filename>.
1594 1595 1596
        The first found file is used.  The user either picks from these
        sessions or GDM will look inside the file <filename>~/.dmrc</filename>
        for the stored preference.
1597 1598 1599
      </para>

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

      <para> 
1610 1611 1612 1613 1614 1615 1616 1617 1618 1619
        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
1620
        this points to a fake generated X servers file for use with the sessreg
1621
        accounting application.
1622 1623 1624
      </para>

      <para>
1625 1626 1627 1628
        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.
1629 1630
      </para>

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

1645
      <para> 
1646 1647 1648 1649 1650
        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.
1651
      </para>
1652
    </sect2>
1653

1654
    <sect2 id="configfile">
1655 1656
      <title>The Configuration Files - <filename>defaults.conf</filename> and
             <filename>custom.conf</filename></title>
1657 1658
      
      <para>
1659 1660 1661 1662 1663 1664 1665
        GDM uses two configuration files:
        <filename>&lt;share&gt;/gdm/defaults.conf</filename>
        and <filename>&lt;etc&gt;/gdm/custom.conf</filename>.  The
        <filename>&lt;share&gt;/gdm/defaults.conf</filename> file contains the
        default configuration choices for GDM, and should not be modified by
        the user.  The <filename>&lt;etc&gt;/gdm/custom.conf</filename>
        file is where users may specify their custom configuration choices.  
1666
        Configuration options specified in the