Overview

2.3. Functional Description

TODO - Would be good to discuss D-Bus, perhaps the new GObject model, and to explain the reasons why the rewrite made GDM better. From a high-level overview perspective, rather than the technical aspects.

GDM 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 "Configuring GDM" section of this document. GDM is also accessible for users with disabilities.

GDM provides the ability to manage the main console display, and displays launched via VT. It is integrated with other programs, such as the Fast User Switch Applet (FUSA) and gnome-screensaver to manage multiple displays on the console via the Xserver Virtual Terminal (VT) interface. It also can manage XDMCP displays.

GDM 2.20 and earlier supported the ability to manage multiple displays with separate graphics cards, such as used in terminal server environments, login in a window via a program like Xnest or Xephyr, the gdmsetup program, XML-based greeter themes, and the ability to run the XDMCP chooser from the login screen. These features are the most serious regressions in the new version of GDM.

Regardless of the display type, GDM will do the following when it manages the display. It will start an Xserver process, then run the Init script as the root user, and start the greeter program on the display.

The greeter program is run as the unpriviledged "gdm" user/group. This user and group are described in the "Security" section of this document. The main function of the greeter program is to authenticate the user. The authentication process is driven by Pluggable Authentication Modules (PAM). The PAM modules determine what prompts (if any) are shown to the user to authenticate. On the average system, the greeter program will request a username and password for authentication. However some systems may be configured to use alternative mechanisms such as a fingerprint or SmartCard reader. GDM and PAM can be configured to not require any input, which will cause GDM to avoid displaying the greeter and simply start a session, which can be useful for some environments, such as for kiosks. Automatic and timed login are examples of how this can be configured via GDM.

In addition to authentication, the greeter program allows the user to select which session to start and which language to use. Sessions are defined by files that end in the .desktop suffix and more information about these files can be found in the "Configuration" section of this document. By default, GDM is configured to display a face browser so the user can select their user account by clicking on an image instead of having to type their username. GDM keeps track of the user's default session and language in the user's ~/.dmrc and will use these defaults if the user did not pick a session or language in the login GUI.

After authenticating a user, the daemon runs the PostLogin script as root, then runs the PreSession script as root. After running these scripts, the user session is started. When the user exits their session, the PostSession script is run as root. These scripts are provided as hooks for distributions and end-users to customize how sessions are managed. For example, using these hooks you could set up a machine which creates the user's $HOME directory on the fly, and erases it on logout. The difference between the PostLogin and PreSession scripts is that PostLogin is run before the pam_open_session call so is the right place to do anything which should be run before the user session is initialized. The PreSession script is called after session initialization.

2.6. The GDM Face Browser

TODO - Is the following correct? Should we describe GNOME preferences integration at all? Can't you specify the face browser via preferences? Not sure. Also is not the face browser configurable? Would be good to talk a bit about how NFS/NIS issues are handled, if that has been improved.

The Face Browser is the interface which allows users to select their username by clicking on an image. This feature can be enabled or disabled via the GDM configuration, and is on by default. When disabled, users must type their username by hand. When enabled, it displays all users which are available on the local system (all users defined in the /etc/passwd file). The Face Browser may not be appropriate to use in some environments.

The Face Browser is configured to display the users who log in most frequently at the top of the list. This helps to ensure that users who log in frequently can quickly find their login image.

The icons used by GDM can be installed globally by the sysadmin or can be located in the user's home directories. If installed globally they should be in the <share>/pixmaps/faces/ directory and the filename should be the name of the user. Face image files should be a standard image that GTK+ can read, such as PNG or JPEG. Face icons placed in the global face directory must be readable to the GDM user.

TODO - In the old GDM the ~/gnome2/gdm file is used, but the new code seems to use ~/.gnome/gdm. Error?

If there is no global icon for the user, GDM will look in the user's $HOME directory for the image file. GDM will first look for the user's face image in ~/.face. If not found, it will try ~/.face.icon. If still not found, it will use the value defined for "face/picture=" in the ~/.gnome2/gdm file.

If a user has no defined face image, GDM will use the "stock_person" icon defined in the current GTK+ theme. If no such image is defined, it will fallback to a generic face image.

Please note that loading and scaling face icons located in user home directories can be a very time-consuming task. Since it not practical to load images over NIS or NFS, GDM does not attempt to load face images from remote home directories. Furthermore, GDM will give up loading face images after 5 seconds of activity and will only display the users whose pictures it has gotten so far. The Include configuration option can be used to specify a set of users who should appear on the face browser. As long as the users to include is of a reasonable size, there should not be a problem with GDM being unable to access the face images. To work around such problems, it is recommended to place face images in the directory specified by the GlobalFaceDir configuration option.

When the browser is turned on, valid usernames on the computer are exposed for everyone to see. If XDMCP is enabled, then the usernames are exposed to remote users. This, of course, limits security somewhat since a malicious user does not need to guess valid usernames. The Face Browser feature is very useful in most environments where a few people use a shared laptop, for example in a home setting or with a laptop.

This is an example of a configuration setting that some Operating Systems might disable by default. Operating Systems that rely on NIS or NFS working well out of the box would likely not want this feature on by default.

2.7. XDMCP

TODO - What XDMCP features actually work? I know that the chooser is missing.

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.

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 default configuration should work reasonably most systems.

GDM by default listens for XDMCP requests on the normal UDP port used for XDMCP, port 177, and will respond to QUERY and BROADCAST_QUERY requests by sending a WILLING packet to the originator.

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

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

Refer to the "Security" section for information about security concerns when using XDMCP.

2.8. Logging

GDM uses syslog to log errors and status. It can also log debugging information, which can be useful for tracking down problems if GDM is not working properly. This can be enabled by starting the GDM daemon with the "--debug" option.

Output from the various Xservers is stored in the GDM log directory, which is normally <var>/log/gdm/. Any Xserver messages are saved to a file associated with the display value, <display>.log.

TODO - Is the 10 second feature below still a feature? Also does the $HOME/.xsession-errors file still work as described. I seem to remember Ray talking about changing how this worked in the rewrite, though I can not remember any details. Is the 200kb cap on the file size or the /tmp/xses-XXXXXX interfaces still supported?

The output from the user session is redirected to ~/.xsession-errors before even the PreSession script is started. So it is not necessary to redirect this again in the session setup script. 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 hopefully know how to correct the problem.

You can suppress the 10 second warning by returning code 66 from the Xsessionscript or from your session binary (the default Xsession script propagates those codes back). This is useful if you have some sort of special logins for which it is not an error to return less then 10 seconds later, or if you setup the session to already display some error message and the GDM message would be confusing and redundant.

The session output is piped through the GDM daemon, so the ~/.xsession-errors file is not allowed to grow larger than 200 kilobytes. Some programs that are run in the user session may generate a lot of output, so limiting its size prevents the file from filling up the disk if the session is left open for a long period of time. The file is overwritten on each login, so logging out and logging back into the same user via GDM will cause any messages from the previous session to be lost. 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.

Note that if GDM can not open this file for some reason, then a fallback file will be created in the /tmp directory named /tmp/xses-<user>.XXXXXX where the XXXXXX are some random characters.

Note that the ~/.xsession-errors and /tmp/xses-XXXXXX interfaces are configured differently on some Operating Systems. If these files do not get created by GDM, then check with your Operating System documention and note if the user session output is logged differently.