diff options
Diffstat (limited to 'docs/C/index.docbook')
| -rw-r--r-- | docs/C/index.docbook | 2279 |
1 files changed, 2279 insertions, 0 deletions
diff --git a/docs/C/index.docbook b/docs/C/index.docbook new file mode 100644 index 0000000..134b9bc --- /dev/null +++ b/docs/C/index.docbook @@ -0,0 +1,2279 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ + <!ENTITY legal SYSTEM "legal.xml"> + <!ENTITY version "2.26.0"> + <!ENTITY date "02/10/2009"> + <!ENTITY mdash "—"> + <!ENTITY percnt "%"> +]> + +<article id="index" lang="en"> + <articleinfo> + <title>GNOME Display Manager Reference Manual</title> + + <revhistory> + <revision> + <revnumber>0.0</revnumber> + <date>2008-09</date> + </revision> + </revhistory> + + <abstract role="description"> + <para> + GDM is the GNOME Display Manager, a graphical login program. + </para> + </abstract> + + <authorgroup> + <author> + <firstname>Martin</firstname><othername>K.</othername> + <surname>Petersen</surname> + <affiliation> + <address><email>mkp@mkp.net</email></address> + </affiliation> + </author> + <author> + <firstname>George</firstname><surname>Lebl</surname> + <affiliation> + <address><email>jirka@5z.com</email></address> + </affiliation> + </author> + <author> + <firstname>Jon</firstname><surname>McCann</surname> + <affiliation> + <address><email>mccann@jhu.edu</email></address> + </affiliation> + </author> + <author> + <firstname>Ray</firstname><surname>Strode</surname> + <affiliation> + <address><email>rstrode@redhat.com</email></address> + </affiliation> + </author> + <author role="maintainer"> + <firstname>Brian</firstname><surname>Cameron</surname> + <affiliation> + <address><email>Brian.Cameron@Oracle.COM</email></address> + </affiliation> + </author> + </authorgroup> + <copyright> + <year>1998</year> + <year>1999</year> + <holder>Martin K. Petersen</holder> + </copyright> + <copyright> + <year>2001</year> + <year>2003</year> + <year>2004</year> + <holder>George Lebl</holder> + </copyright> + <copyright> + <year>2003</year> + <year>2007</year> + <year>2008</year> + <holder>Red Hat, Inc.</holder> + </copyright> + <copyright> + <year>2003</year> + <year>2011</year> + <holder>Oracle and/or its affiliates. All rights reserved.</holder> + </copyright> + + &legal; + + <releaseinfo> + This manual describes version &version; of the GNOME Display Manager. + It was last updated on &date;. + </releaseinfo> + </articleinfo> + + <!-- ============= Preface ================================== --> + + <sect1 id="preface"> + <title>Terms and Conventions Used in This Manual</title> + + <para> + This manual describes version &version; of the GNOME Display Manager. + It was last updated on &date;. + </para> + + <para> + Chooser - A program used to select a remote host for managing a + display remotely on the attached display (<command>gdm-host-chooser</command>). + </para> + + <para> + FreeDesktop - The organization providing desktop standards, such as the + Desktop Entry Specification used by GDM. + <ulink type="http" url="http://www.freedesktop.org/"> + http://www.freedesktop.org</ulink>. + </para> + <para> + GDM - GNOME Display Manager. Used to describe the software package as a + whole. + </para> + + <para> + Greeter - The graphical login window (provided by <command>gnome-shell</command>). + </para> + + <para> + PAM - Pluggable Authentication Mechanism + </para> + + <para> + XDMCP - X Display Manage Protocol + </para> + + <para> + Xserver - An implementation of the X Window System. For example the + Xorg Xserver provided by the X.org Foundation + <ulink type="http" url="http://www.x.org/">http://www.x.org</ulink>. + </para> + + <para> + Paths that start with a word in angle brackets are relative to the + installation prefix. I.e. <filename><share>/pixmaps/</filename> + refers to <filename>/usr/share/pixmaps</filename> if GDM was + configured with <command>--prefix=/usr</command>. + </para> + </sect1> + + <!-- ============= Overview ================================= --> + + <sect1 id="overview"> + <title>Overview</title> + + <sect2 id="introduction"> + <title>Introduction</title> + + <para> + The GNOME Display Manager (GDM) is a display manager that implements + all significant features required for managing attached and remote + displays. GDM was written from scratch and does not contain any XDM or + X Consortium code. + </para> + + <para> + Note that GDM is configurable, and many configuration settings have + an impact on security. Issues to be aware of are highlighted in this + document. + </para> + + <para> + Please note that some Operating Systems configure GDM to behave + differently than the default values as described in this document. If + GDM does not seem to behave as documented, then check to see if any + related configuration may be different than described here. + </para> + + <para> + For further information about GDM, refer to the project website at + <ulink type="http" url="http://wiki.gnome.org/Projects/GDM/"> + http://wiki.gnome.org/Projects/GDM</ulink>. + </para> + + <para> + For discussion or queries about GDM, refer to the + <address><email>gdm-list@gnome.org</email></address> mail list. This + list is archived, and is a good resource to check to seek answers to + common questions. This list is archived at + <ulink type="http" url="http://mail.gnome.org/archives/gdm-list/"> + http://mail.gnome.org/archives/gdm-list/</ulink> and has a search + facility to look for messages with keywords. + </para> + + <para> + Please submit any bug reports or enhancement requests to the + "gdm" category in + <ulink type="http" url="http://bugzilla.gnome.org/"> + http://bugzilla.gnome.org</ulink>. + </para> + </sect2> + + <sect2 id="stability"> + <title>Interface Stability</title> + + <para> + GDM 2.20 and earlier supported stable configuration interfaces. + However, the codebase was completely rewritten for GDM 2.22, and + is not completely backward compatible with older releases. This is + in part because things work differently, so some options just don't + make sense, in part because some options never made sense, and in + part because some functionality has not been reimplemented yet. + </para> + + <para> + Interfaces which continue to be supported in a stable fashion include + the Init, PreSession, PostSession, PostLogin, and Xsession scripts. + Some daemon configuration options in the + <filename><etc>/gdm/custom.conf</filename> file continue to be + supported. Also, the <filename>~/.dmrc</filename>, and face browser + image locations are still supported. + </para> + + <para> + 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 were not + added back during the 2.22 rewrite. + </para> + + </sect2> + + <sect2 id="functionaldesc"> + <title>Functional Description</title> + +<!-- +<para> + 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. +</para> +--> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <para> + Regardless of the display type, GDM will do the following when it + manages the display. It will start an Xserver process, then run the + <filename>Init</filename> script as the root user, and start the + greeter program on the display. + </para> + + <para> + The greeter program is run as the unprivileged "gdm" + user/group. This user and group are described in the + "Security" section of this document. The main functions of + the greeter program are to provide a mechanism for selecting + an account for log in and to drive the dialogue between + the user and system when authenticating that account. 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 supplemental mechanisms such as a fingerprint or + SmartCard readers. GDM can be configured to support these + alternatives in parallel with greeter login extensions and the + <command>--enable-split-authentication</command> + <filename>./configure</filename> option, or one at a + time via system PAM configuration. + </para> + + <para> + The smartcard extension can be enabled or disabled via the + <filename>org.gnome.display-manager.extensions.smartcard.active</filename> + gsettings key. + </para> + + <para> + Likewise, the fingerprint extension can be enabled or disabled via the + <filename>org.gnome.display-manager.extensions.fingerprint.active</filename> + gsettings key. + </para> + + <para> + GDM and PAM can be configured to not require any + input, which will cause GDM to automatically log in and simply + start a session, which can be useful for some environments, such as + single user systems or kiosks. + </para> + + <para> + 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 "GDM User Session and Language + 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 + <filename>~/.dmrc</filename> and will use these defaults if the user + did not pick a session or language in the login GUI. + </para> + + <para> + After authenticating a user, the daemon runs the + <filename>PostLogin</filename> script as root, then runs the + <filename>PreSession</filename> script as root. After running these + scripts, the user session is started. When the user exits their + session, the <filename>PostSession</filename> 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 <filename>PostLogin</filename> and + <filename>PreSession</filename> scripts is that + <filename>PostLogin</filename> 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 <filename>PreSession</filename> + script is called after session initialization. + </para> + </sect2> + + <sect2 id="greeterpanel"> + <title>Greeter Panel</title> + <para> + The GDM greeter program displays a panel docked at the bottom of the + screen which provides additional functionality. When a user is + selected, the panel allows the user to select which session, language, + and keyboard layout to use after logging in. The keyboard layout + selector also changes the keyboard layout used when typing your + password. The panel also contains an area for login services to leave + status icons. Some example status icons include a battery icon for + current battery usage, and an icon for enabling accessibility features. + The greeter program also provides buttons which allow the user to + shutdown or restart the system. It is possible to configure GDM to not + provide the shutdown and restart buttons, if desired. GDM can also be + configured via PolicyKit (or via RBAC on Oracle Solaris) to require the + user have appropriate authorization before accepting the shutdown or + restart request. + </para> + + <para> + Note that keyboard layout features are only available on systems that + support libxklavier. + </para> + </sect2> + + <sect2 id="accessibility"> + <title>Accessibility</title> + + <para> + GDM supports "Accessible Login", allowing users to log into + their desktop session even if they cannot easily use the screen, + mouse, or keyboard in the usual way. Accessible Technology (AT) + features such as an on-screen keyboard, screen reader, screen + magnifier, and Xserver AccessX keyboard accessibility are available. + It is also possible to enable large text or high contrast icons and + controls, if needed. Refer to the "Accessibility + Configuration" section of the document for more information + how various accessibility features can be configured. + </para> + + <para> + On some Operating Systems, it is necessary to make sure that the GDM + user is a member of the "audio" group for AT programs that + require audio output (such as text-to-speech) to be functional. + </para> + </sect2> + + <sect2 id="facebrowser"> + <title>The GDM Face Browser</title> + + <para> + 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 org.gnome.login-screen disable-user-list GSettings + key and is on by default. When disabled, users must type their + complete username by hand. When enabled, it displays all local users + which are available for login on the system (all user accounts defined + in the /etc/passwd file that have a valid shell and sufficiently high + UID) and remote users that have recently logged in. + The face browser in GDM 2.20 and earlier would attempt to display all + remote users, which caused performance problems in large, + enterprise deployments. + </para> + + <para> + 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. + </para> + + <para> + The Face Browser supports "type-ahead search" which dynamically + moves the face selection as the user types to the corresponding username + in the list. This means that a user with a long username will only + have to type the first few characters of the username before the correct + item in the list gets selected. + </para> + + <para> + 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 <filename><share>/pixmaps/faces/</filename> + 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. + </para> + +<!-- +<para> + TODO - In the old GDM the ~/gnome2/gdm file is used, but the new code + seems to use ~/.gnome/gdm. Error? +</para> +--> + <para> + 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 <filename>~/.face</filename>. If not found, it will try + <filename>~/.face.icon</filename>. If still not found, it will use the + value defined for "face/picture=" in the + <filename>~/.gnome2/gdm</filename> file. + </para> + + <para> + If a user has no defined face image, GDM will use the + "stock_person" icon defined in the current GTK+ theme. If no + such image is defined, it will fallback to a generic face image. + </para> + + <para> + Please note that loading and scaling face icons located in remote 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. + </para> + + <para> + 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. + In some very restrictive environments the face browser may not be + appropriate. + </para> + + </sect2> + + <sect2 id="xdmcp"> + <title>XDMCP</title> + +<!-- +<para> + TODO - What XDMCP features actually work? I know that the + chooser is missing. +</para> +--> + + <para> + The GDM daemon can be configured to listen for and manage X Display + Manage Protocol (XDMCP) requests from remote displays. By default + XDMCP support is turned off, but can be enabled if desired. If GDM is + built with TCP Wrapper support, then the daemon will only grant access + to hosts specified in the GDM service section in the TCP Wrappers + configuration file. + </para> + + <para> + GDM includes several measures making it more resistant to denial of + service attacks on the XDMCP service. A lot of the protocol + parameters, handshaking timeouts, etc. can be fine tuned. The default + configuration should work reasonably on most systems. + </para> + + <para> + 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. + </para> + + <para> + GDM can also be configured to honor INDIRECT queries and present a + host chooser to the remote display. GDM will remember the user's + choice and forward subsequent requests to the chosen manager. GDM + also supports an extension to the protocol which will make it forget + the redirection once the user's connection succeeds. This extension + is only supported if both daemons are GDM. It is transparent and + will be ignored by XDM or other daemons that implement XDMCP. + </para> + + <para> + If XDMCP seems to not be working, make sure that all machines are + specified in <filename>/etc/hosts</filename>. + </para> + + <para> + Refer to the "Security" section for information about + security concerns when using XDMCP. + </para> + </sect2> + + <sect2 id="logging"> + <title>Logging</title> + + <para> + 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. Debug output can be enabled by setting the + debug/Enable key to "true" in the + <filename><etc>/gdm/custom.conf</filename> file. + </para> + + <para> + Output from the various Xservers is stored in the GDM log directory, + which is normally <filename><var>/log/gdm/</filename>. Any + Xserver messages are saved to a file associated with the display value, + <filename><display>.log</filename>. + </para> + + <para> + The session output is piped through the GDM daemon to the + <filename>~/<replaceable>$XDG_CACHE_HOME</replaceable>/gdm/session.log</filename> + file which usually expands to <filename>~/.cache/gdm/session.log</filename>. + 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. + </para> + + <para> + Note that if GDM can not create this file for some reason, then a + fallback file will be created named <filename>~/<replaceable>$XDG_CACHE_HOME</replaceable>/gdm/session.log.XXXXXXXX</filename> + where the <filename>XXXXXXXX</filename> are some random characters. + </para> + </sect2> + + <sect2 id="fusa"> + <title>Fast User Switching</title> + + <para> + GDM allows multiple users to be logged in at the same time. After one + user is logged in, additional users can log in via the User Switcher + on the GNOME Panel, or from the "Switch User" button in Lock Screen dialog + of GNOME Screensaver. The active session can be changed back and forth using + the same mechanism. Note that some distributions may not add the User Switcher + to the default panel configuration. It can be added using the panel context + menu. + </para> + <para> + Note this feature is available on systems that support Virtual + Terminals. This feature will not function if Virtual Terminals is not + available. + </para> + </sect2> + </sect1> + + <!-- ============= Security ================================= --> + + <sect1 id="security"> + <title>Security</title> + + <sect2 id="gdmuser"> + <title>The GDM User And Group</title> + + <para> + For security reasons a dedicated user and group id are recommended for + proper operation. This user and group are normally "gdm" on + most systems, but can be configured to any user or group. All GDM + GUI programs are run as this user, so that the programs which interact + with the user are run in a sandbox. This user and group should have + limited privilege. + </para> + + <para> + The only special privilege the "gdm" user requires is the + ability to read and write Xauth files to the + <filename><var>/run/gdm</filename> directory. The + <filename><var>/run/gdm</filename> directory should have + root:gdm ownership and 1777 permissions. + </para> + + <para> + You should not, under any circumstances, configure the GDM user/group + to a user which a user could easily gain access to, such as the user + <filename>nobody</filename>. Any user who gains access to an Xauth + key can snoop on and control running GUI programs running in the + associated session or perform a denial-of-service attack on it. It + is important to ensure that the system is configured properly so that + only the "gdm" user has access to these files and that it + is not easy to login to this account. For example, the account should + be setup to not have a password or allow non-root users to login to the + account. + </para> + + <para> + The GDM greeter configuration is stored in GConf. To allow the GDM + user to be able to write configuration, it is necessary for the + "gdm" user to have a writable $HOME directory. Users may + configure the default GConf configuration as desired to avoid the + need to provide the "gdm" user with a writable $HOME + directory. However, some features of GDM may be disabled if it is + unable to write state information to GConf configuration. + </para> + </sect2> + + <sect2 id="PAM"> + <title>PAM</title> + + <para> + GDM uses PAM for login authentication. PAM stands for Pluggable + Authentication Module, and is used by most programs that request + authentication on your computer. It allows the administrator to + configure specific authentication behavior for different login programs + (such as ssh, login GUI, screensaver, etc.) + </para> + + <para> + PAM is complicated and highly configurable, and this documentation does + not intend to explain this in detail. Instead, it is intended to give + an overview of how PAM configuration relates with GDM, how PAM is + commonly configured with GDM, and known issues. It is expected that + a person needing to do PAM configuration would need to do further + reading of PAM documentation to understand how to configure PAM and + to understand terms used in this section. + </para> + + <para> + PAM configuration has different, but similar, interfaces on different + Operating Systems, so check the + <ulink type="help" url="man:pam.d">pam.d</ulink> or + <ulink type="help" url="man:pam.conf">pam.conf</ulink> man page for + details. Be sure you read the PAM documentation and are comfortable + with the security implications of any changes you intend to make to + your configuration. + </para> + + <para> + Note that, by default, GDM uses the "gdm" PAM service name + for normal login and the "gdm-autologin" PAM service name for + automatic login. These services may not be defined in your pam.d or + pam.conf configured file. If there is no entry, then GDM will use the + default PAM behavior. On most systems this should work fine. + However, the automatic login feature may not work if the gdm-autologin + service is not defined. + </para> + + <para> + The <filename>PostLogin</filename> script is run before + pam_open_session is called, and the <filename>PreSession</filename> + script is called after. This allows the system administrator to add + any scripting to the login process either before or after PAM + initializes the session. + </para> + + <para> + If you wish to make GDM work with other types of authentication + mechanisms (such as a fingerprint or SmartCard reader), then you should + implement this by using a PAM service module for the desired + authentication type rather than by trying to modify the GDM code + directly. Refer to the PAM documentation on your system. How to do + this is frequently discussed on the + <address><email>gdm-list@gnome.org</email></address> mail list, + so you can refer to the list archives for more information. + </para> + + <para> + PAM does have some limitations regarding being able to work with + multiple types of authentication at the same time, like supporting + the ability to accept either SmartCard and the ability to type the + username and password into the login program. There are techniques + that are used to make this work, and it is best to research how this + problem is commonly solved when setting up such a configuration. + </para> + + <para> + If automatic login does not work on a system, check to see if the + "gdm-autologin" PAM stack is defined in the PAM configuration. For + this to work, it is necessary to use a PAM module that simply does no + authentication, or which simply returns PAM_SUCCESS from all of its + public interfaces. Assuming your system has a pam_allow.so PAM module + which does this, a PAM configuration to enable "gdm-autologin" would + look like this: + </para> + +<screen> + gdm-autologin auth required pam_unix_cred.so.1 + gdm-autologin auth sufficient pam_allow.so.1 + gdm-autologin account sufficient pam_allow.so.1 + gdm-autologin session sufficient pam_allow.so.1 + gdm-autologin password sufficient pam_allow.so.1 +</screen> + + <para> + The above setup will cause no lastlog entry to be generated. If a + lastlog entry is desired, then use the following for the session: + </para> + +<screen> + gdm-autologin session required pam_unix_session.so.1 +</screen> + + <para> + If the computer is used by several people, which makes automatic login + unsuitable, you may want to allow some users to log in without entering + their password. This feature can be enabled as a per-user option in + the users-admin tool from the gnome-system-tools; it is achieved by + checking that the user is member a Unix group called + "nopasswdlogin" before asking for a password. For this to work, + the PAM configuration file for the "gdm" service must include + a line such as: + </para> + +<screen> + gdm auth sufficient pam_succeed_if.so user ingroup nopasswdlogin +</screen> + + </sect2> + + <sect2 id="utmpwtmp"> + <title>utmp and wtmp</title> + + <para> + GDM generates utmp and wtmp User Accounting Database entries upon + session login and logout. The utmp database contains user access + and accounting information that is accessed by commands such as + <command>finger</command>, <command>last</command>, + <command>login</command>, and <command>who</command>. The wtmp + database contains the history of user access and accounting + information for the utmp database. Refer to the + <ulink type="help" url="man:utmp">utmp</ulink> and + <ulink type="help" url="man:wtmp">wtmp</ulink> + man pages on your system for more information. + </para> + </sect2> + + <sect2 id="xauth"> + <title>Xserver Authentication Scheme</title> + + <para> + Xserver authorization files are stored in a newly created subdirectory + of <filename><var>/run/gdm</filename> at start up. These files + are used to store and share a "password" between X clients + and the Xserver. This "password" is unique for each session + logged in, so users from one session can't snoop on users from another. + </para> + + <para> + GDM only supports the MIT-MAGIC-COOKIE-1 Xserver 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 Xserver 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. In most cases, + ssh -Y should be preferred over GDM's XDMCP features. + </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. This type of set up + should never use an unmanaged hub or other sniffable network. + </para> + + </sect2> + + <sect2 id="xdmcpaccess"> + <title>XDMCP Access Control</title> + + <para> + XDMCP access control is done using TCP wrappers. It is possible to + compile GDM without TCP wrapper support, so this feature may not be + supported on some Operating Systems. + </para> + + <para> + You should use the daemon name <command>gdm</command> in the + <filename><etc>/hosts.allow</filename> and + <filename><etc>/hosts.deny</filename> files. For example to + deny computers from <filename>.evil.domain</filename> from logging in, + then add + </para> +<screen> +gdm: .evil.domain +</screen> + <para> + to <filename><etc>/hosts.deny</filename>. You may also need + to add + </para> +<screen> +gdm: .your.domain +</screen> + <para> + to your <filename><etc>/hosts.allow</filename> if you normally + disallow all services from all hosts. See the + <ulink type="help" url="man:hosts.allow">hosts.allow(5)</ulink> man + page for details. + </para> + </sect2> + + <sect2 id="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 really needed. GDM + guards against 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 do a denial of service attack via XDMCP than attacking a + webserver. + </para> + + <para> + It is also wise to block all of the Xserver ports. These are TCP + ports 6000+ (one for each display number) 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 when using it over the Internet, and + XDMCP is even less safe. + </para> + </sect2> + + <sect2 id="policykit"> + <title>PolicyKit</title> + +<!-- +<para> + TODO - Should we say more? +</para> +--> + + <para> + GDM may be configured to use PolicyKit to allow the system + administrator to control whether the login screen should provide + the shutdown and restart buttons on the greeter screen. + </para> + + <para> + These buttons are controlled by the + <filename>org.freedesktop.consolekit.system.stop-multiple-users</filename> + and + <filename>org.freedesktop.consolekit.system.restart-multiple-users</filename> + actions respectively. Policy for these actions can be set up using the + polkit-gnome-authorization tool, or the polkit-auth command line program. + </para> + + </sect2> + + <sect2 id="rbac"> + <title>RBAC (Role Based Access Control)</title> + + <para> + GDM may be configured to use RBAC instead of PolicyKit. In this + case the RBAC configuration is used to control whether the login screen + should provide the shutdown and restart buttons on the greeter screen. + </para> + + <para> + For example, on Oracle Solaris, the "solaris.system.shutdown" + authorization is used to control this. Simply modify the + <filename>/etc/user_attr</filename> file so that the "gdm" + user has this authorization. + </para> + </sect2> + + </sect1> + + <!-- ============= ConsoleKit ================================ --> + + <sect1 id="consolekit"> + <title>Support for ConsoleKit</title> + +<!-- +<para> + TODO - Should we update these docs? Probably should mention any + configuration that users may want to do for using it with GDM? + If so, perhaps this section should be moved to a subsection of + the "Configure" section? +</para> +--> + + <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 attached, etc. As the entity that initiates the user process, + GDM is in a unique position to know about the user session and to be + trusted to provide these bits of information. The use of this privileged + method is restricted by the use of the D-Bus system message bus security + policy. + </para> + + <para> + In case a user with an existing session 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 are + 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> + </sect1> + + <!-- ============= Configuration ============================= --> + + <sect1 id="configuration"> + <title>Configuration</title> + + <para> + GDM has a number of configuration interfaces. These include scripting + integration points, daemon configuration, greeter configuration, + general session settings, integration with gnome-settings-daemon + configuration, and session configuration. These types of integration are + described in detail below. + </para> + + <sect2 id="scripting"> + <title>Scripting Integration Points</title> + + <para> + The GDM script integration points can be found in the + <filename><etc>/gdm/</filename> directory: + </para> + +<screen> +Xsession +Init/ +PostLogin/ +PreSession/ +PostSession/ +</screen> + + <para> + The <filename>Init</filename>, <filename>PostLogin</filename>, + <filename>PreSession</filename>, and <filename>PostSession</filename> + scripts all work as described below. + </para> + + <para> + For each type of script, the default one which will be executed is + called "Default" and is stored in a directory associated with + the script type. So the default <filename>Init</filename> script is + <filename><etc>/gdm/Init/Default</filename>. A per-display + script can be provided, and if it exists it will be run instead of the + default script. Such scripts are stored in the same directory as the + default script and have the same name as the Xserver DISPLAY value for + that display. For example, if the <filename><Init>/:0</filename> + script exists, it will be run for DISPLAY ":0". + </para> + + <para> + All of these scripts are run with root privilege and return 0 if run + successfully, and a non-zero return code if there was any failure that + should cause the login session to be aborted. Also note that GDM will + block until the scripts finish, so if any of these scripts hang, this + will cause the login process to also hang. + </para> + + <para> + When the Xserver for the login GUI has been successfully started, but + before the login GUI is actually displayed, GDM will run the + <filename>Init</filename> script. This script is useful for starting + programs that should be run while the login screen is showing, or for + doing any special initialization if required. + </para> + + <para> + After the user has been successfully authenticated GDM will run the + <filename>PostLogin</filename> script. This is done before any session + setup has been done, including before the pam_open_session call. This + script is useful for doing any session initialization that needs to + happen before the session starts. For example, you might setup the + user's $HOME directory if needed. + </para> + + <para> + After the user session has been initialized, GDM will run the + <filename>PreSession</filename> script. This script is useful for + doing any session initialization that needs to happen after the + session has been initialized. It can be used for session management or + accounting, for example. + </para> + + <para> + When a user terminates their session, GDM will run the + <filename>PostSession</filename> script. Note that the Xserver will + have been stopped by the time this script is run, so it should not be + accessed. + </para> + + <para> + Note that the <filename>PostSession</filename> script will be run + even when the display fails to respond due to an I/O error or + similar. Thus, there is no guarantee that X applications will work + during script execution. + </para> + + <para> + All of the above scripts will set the + <filename>$RUNNING_UNDER_GDM</filename> environment variable to + <filename>yes</filename>. If the scripts are also shared with other + display managers, this allows you to identify when GDM is calling these + scripts, so you can run specific code when GDM is used. + </para> + </sect2> + + <sect2 id="autostart"> + <title>Autostart Configuration</title> + + <para> + The <filename><share>/gdm/autostart/LoginWindow</filename> + directory contains files in the format specified by the + "FreeDesktop.org Desktop Application Autostart + Specification". Standard features in the specification may be + used to specify programs that should auto-restart or only be launched + if a GConf configuration value is set, etc. + </para> + + <para> + Any <filename>.desktop</filename> files in this directory will cause + the associated program to automatically start with the login GUI + greeter. By default, GDM is shipped with files which will autostart + the gdm-simple-greeter login GUI greeter itself, the + gnome-power-manager application, the gnome-settings-daemon, and the + metacity window manager. These programs are needed for the greeter + program to work. In addition, desktop files are provided for starting + various AT programs if the configuration values specified in the + Accessibility Configuration section below are set. + </para> + </sect2> + + <sect2 id="xsessionscript"> + <title>Xsession Script</title> + + <para> + There is also an <filename>Xsession</filename> script located at + <filename><etc>/gdm/Xsession</filename> which is called between + the <filename>PreSession</filename> and the + <filename>PostSession</filename> scripts. This script does not + support per-display like the other scripts. This script is used for + actually starting the user session. This script is run as the user, + and it will run whatever session was specified by the Desktop session + file the user selected to start. + </para> + </sect2> + + <sect2 id="daemonconfig"> + <title>Daemon Configuration</title> + + <para> + The GDM daemon is configured using the + <filename><etc>/gdm/custom.conf</filename> file. Default + values are stored in GConf in the <filename>gdm.schemas</filename> + file. It is recommended that end-users modify the + <filename><etc>/gdm/custom.conf</filename> file because the + schemas file may be overwritten when the user updates their system to + have a newer version of GDM. + </para> + + <para> + Note that older versions of GDM supported additional configuration + options which are no longer supported in the latest versions of GDM. + </para> + + <para> + The <filename><etc>/gdm/custom.conf</filename> file is in the + <filename>keyfile</filename> format. Keywords in brackets + define group sections, strings before an equal sign (=) are keys and + the data after equal sign represents their value. Empty lines or + lines starting with the hash mark (#) are ignored. + </para> + + <para> + The file <filename><etc>/gdm/custom.conf</filename> supports the + "[daemon]", "[security]", and "[xdmcp]" + group sections. Within each group, there are particular key/value + pairs that can be specified to modify how GDM behaves. For example, + to enable timed login and specify the timed login user to be a user + named "you", you would modify the file so it contains the + following lines: + </para> + +<screen> +[daemon] +TimedLoginEnable=true +TimedLogin=you +</screen> + + <para> + A full list of supported configuration keys follow: + </para> + + <sect3 id="choosersection"> + <title>[chooser]</title> + <variablelist> + + <varlistentry> + <term>Multicast</term> + <listitem> + <synopsis>Multicast=false</synopsis> + <para> + If true and IPv6 is enabled, the chooser will send a multicast + query to the local network and collect responses from the hosts + who have joined multicast group. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MulticastAddr</term> + <listitem> + <synopsis>MulticastAddr=ff02::1</synopsis> + <para> + This is the Link-local multicast address. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="daemonsection"> + <title>[daemon]</title> + <variablelist> + <varlistentry> + <term>TimedLoginEnable</term> + <listitem> + <synopsis>TimedLoginEnable=false</synopsis> + <para> + If the user given in <filename>TimedLogin</filename> should be + logged in after a number of seconds (set with + <filename>TimedLoginDelay</filename>) of inactivity on the + login screen. This is useful for public access terminals or + perhaps even home use. If the user uses the keyboard or + browses the menus, the timeout will be reset to + <filename>TimedLoginDelay</filename> or 30 seconds, whichever + is higher. If the user does not enter a username but just + hits the ENTER key while the login program is requesting the + username, then GDM will assume the user wants to login + immediately as the timed user. Note that no password will be + asked for this user so you should be careful, although if using + PAM it can be configured to require password entry before + allowing login. Refer to the "Security->PAM" + section of the manual for more information, or for help if this + feature does not seem to work. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>TimedLogin</term> + <listitem> + <synopsis>TimedLogin=</synopsis> + <para> + This is the user that should be logged in after a specified + number of seconds of inactivity. + </para> + <para> + If the value ends with a vertical bar | (the pipe symbol), + then GDM will execute the program specified and use whatever + value is returned on standard out from the program as the user. + The program is run with the DISPLAY environment variable set so + that it is possible to specify the user in a per-display + fashion. For example if the value is "/usr/bin/getloginuser|", + then the program "/usr/bin/getloginuser" will be run to get the + user value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>TimedLoginDelay</term> + <listitem> + <synopsis>TimedLoginDelay=30</synopsis> + <para> + Delay in seconds before the <filename>TimedLogin</filename> + user will be logged in. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AutomaticLoginEnable</term> + <listitem> + <synopsis>AutomaticLoginEnable=false</synopsis> + <para> + If true, the user given in <filename>AutomaticLogin</filename> + should be logged in immediately. This feature is like timed + login with a delay of 0 seconds. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AutomaticLogin</term> + <listitem> + <synopsis>AutomaticLogin=</synopsis> + <para> + This is the user that should be logged in immediately if + <filename>AutomaticLoginEnable</filename> is true. + </para> + <para> + If the value ends with a vertical bar | (the pipe symbol), + then GDM will execute the program specified and use whatever + value is returned on standard out from the program as the user. + The program is run with the DISPLAY environment variable set so + that it is possible to specify the user in a per-display + fashion. For example if the value is "/usr/bin/getloginuser|", + then the program "/usr/bin/getloginuser" will be run to get the + user value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User</term> + <listitem> + <synopsis>User=gdm</synopsis> + <para> + The username under which the greeter and other GUI programs + are run. Refer to the <filename>Group</filename> + configuration key and to the "Security->GDM User And + Group" section of this document for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Group</term> + <listitem> + <synopsis>Group=gdm</synopsis> + <para> + The group name under which the greeter and other GUI programs + are run. Refer to the <filename>User</filename> + configuration key and to the "Security->GDM User And + Group" section of this document for more information. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="debugsection"> + <title>Debug Options</title> + + <variablelist> + <title>[debug]</title> + + <varlistentry> + <term>Enable</term> + <listitem> + <synopsis>Enable=false</synopsis> + <para> + To enable debugging, set the debug/Enable key to + "true" in the + <filename><etc>/gdm/custom.conf</filename> + file and restart GDM. Then debug output will be sent to the + system log file (<filename><var>/log/messages</filename> + or <filename><var>/adm/messages</filename> depending on + your Operating System). + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="greetersection"> + <title>Greeter Options</title> + + <variablelist> + <title>[greeter]</title> + + <varlistentry> + <term>IncludeAll</term> + <listitem> + <synopsis>IncludeAll=true</synopsis> + <para> + If true, then the face browser will show all users on the local + machine. If false, the face browser will only show users who + have recently logged in. + </para> + + <para> + When this key is true, GDM will call fgetpwent() to get a list + of local users on the system. Any users with a user id less + than 500 (or 100 if running on Oracle Solaris) are filtered + out. The Face Browser also will display any users that have + previously logged in on the system (for example NIS/LDAP + users). It gets this list via calling the + <command>ck-history</command> ConsoleKit interface. It will + also filter out any users which do not have a valid shell + (valid shells are any shell that getusershell() returns - + /sbin/nologin or /bin/false are considered invalid shells even + if getusershell() returns them). + </para> + + <para> + If false, then GDM more simply only displays users that have + previously logged in on the system (local or NIS/LDAP users) by + calling the <command>ck-history</command> ConsoleKit interface. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Include</term> + <listitem> + <synopsis>Include=</synopsis> + <para> + Set to a list of users to always include in the Face Browser. + This value is set to a list of users separated by commas. By + default, the value is empty. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Exclude</term> + <listitem> + <synopsis>Exclude=bin,root,daemon,adm,lp,sync,shutdown,halt,mail,news,uucp,operator,nobody,nobody4,noaccess,postgres,pvm,rpm,nfsnobody,pcap</synopsis> + <para> + Set to a list of users to always exclude in the Face Browser. + This value is set to a list of users separated by commas. Note + that the setting in the <filename>custom.conf</filename> + overrides the default value, so if you wish to add additional + users to the list, then you need to set the value to the + default value with additional users appended to the list. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="securitysection"> + <title>Security Options</title> + + <variablelist> + <title>[security]</title> + + <varlistentry> + <term>DisallowTCP</term> + <listitem> + <synopsis>DisallowTCP=true</synopsis> + <para> + If true, then always append <filename>-nolisten tcp</filename> + to the command line when starting attached Xservers, thus + disallowing TCP connection. This is a more secure + configuration if you are not using remote connections. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="xdmcpsection"> + <title>XDCMP Support</title> + + <variablelist> + <title>[xdmcp]</title> + + <varlistentry> + <term>DisplaysPerHost</term> + <listitem> + <synopsis>DisplaysPerHost=1</synopsis> + <para> + To prevent attackers from filling up the pending queue, GDM + will only allow one connection for each remote computer. If + you want to provide display services to computers with more + than one screen, you should increase this value. + </para> + + <para> + Note that the number of attached DISPLAYS allowed is not + limited. Only remote connections via XDMCP are limited by + this configuration option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Enable</term> + <listitem> + <synopsis>Enable=false</synopsis> + <para> + Setting this to true enables XDMCP support allowing remote + displays/X terminals to be managed by GDM. + </para> + + <para> + <filename>gdm</filename> listens for requests on UDP port 177. + See the Port option for more information. + </para> + + <para> + If GDM is compiled to support it, access from remote displays + can be controlled using the TCP Wrappers library. The service + name is <filename>gdm</filename> + </para> + + <para> + You should add +<screen> +gdm:.my.domain +</screen> + to your <filename><etc>/hosts.allow</filename>, depending + on your TCP Wrappers configuration. See the + <ulink type="help" url="man:hosts.allow">hosts.allow</ulink> + man page for details. + </para> + + <para> + Please note that XDMCP is not a particularly secure protocol + and that it is a good idea to block UDP port 177 on your + firewall unless you really need it. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>HonorIndirect</term> + <listitem> + <synopsis>HonorIndirect=true</synopsis> + <para> + Enables XDMCP INDIRECT choosing (i.e. remote execution of + <filename>gdmchooser</filename>) for X-terminals which do not + supply their own display browser. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MaxPending</term> + <listitem> + <synopsis>MaxPending=4</synopsis> + <para> + To avoid denial of service attacks, GDM has fixed size queue + of pending connections. Only MaxPending displays can start at + the same time. + </para> + + <para> + Please note that this parameter does not limit the number of + remote displays which can be managed. It only limits the number + of displays initiating a connection simultaneously. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MaxSessions</term> + <listitem> + <synopsis>MaxSessions=16</synopsis> + <para> + Determines the maximum number of remote display connections + which will be managed simultaneously. I.e. the total number of + remote displays that can use your host. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MaxWait</term> + <listitem> + <synopsis>MaxWait=30</synopsis> + <para> + When GDM is ready to manage a display an ACCEPT packet is sent + to it containing a unique session id which will be used in + future XDMCP conversations. + </para> + + <para> + GDM will then place the session id in the pending queue + waiting for the display to respond with a MANAGE request. + </para> + + <para> + If no response is received within MaxWait seconds, GDM will + declare the display dead and erase it from the pending queue + freeing up the slot for other displays. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MaxWaitIndirect</term> + <listitem> + <synopsis>MaxWaitIndirect=30</synopsis> + <para> + The MaxWaitIndirect parameter determines the maximum number of + seconds between the time where a user chooses a host and the + subsequent indirect query where the user is connected to the + host. When the timeout is exceeded, the information about the + chosen host is forgotten and the indirect slot freed up for + other displays. The information may be forgotten earlier if + there are more hosts trying to send indirect queries then + <filename>MaxPendingIndirect</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>PingIntervalSeconds</term> + <listitem> + <synopsis>PingIntervalSeconds=60</synopsis> + <para> + If the Xserver does not respond in the specified number of + seconds, then the connection is stopped and the session ended. + When this happens the daemon dies with an ALARM signal. + Note that GDM 2.20 and earlier multiplied this setting by 2, + so it may be necessary to increase the timeout if upgrading + from GDM 2.20 and earlier to a newer version. + </para> + + <para> + Note that GDM in the past used to have a + <filename>PingInterval</filename> configuration key which was + also in minutes. For most purposes you'd want this setting + to be lower than one minute. However since in most cases where + XDMCP would be used (such as terminal labs), a lag of more + than 15 or so seconds would really mean that the terminal was + turned off or restarted and you would want to end the session. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Port</term> + <listitem> + <synopsis>Port=177</synopsis> + <para> + The UDP port number <filename>gdm</filename> should listen to + for XDMCP requests. Do not change this unless you know what + you are doing. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Willing</term> + <listitem> + <synopsis>Willing=<etc>/gdm/Xwilling</synopsis> + <para> + When the machine sends a WILLING packet back after a QUERY it + sends a string that gives the current status of this server. + The default message is the system ID, but it is possible to + create a script that displays customized message. If this + script does not exist or this key is empty the default message + is sent. If this script succeeds and produces some output, + the first line of it's output is sent (and only the first + line). It runs at most once every 3 seconds to prevent + possible denial of service by flooding the machine with QUERY + packets. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <sect2 id="greeterconfiguration"> + <title>Simple Greeter Configuration</title> + + <para> + The GDM default greeter is called the simple Greeter and is + configured via GConf. Default values are stored in GConf in the + <filename>gdm-simple-greeter.schemas</filename> file. These defaults + can be overridden if the "gdm" user has a writable $HOME + directory to store GConf settings. These values can be edited using + the <command>gconftool-2</command> or <command>gconf-editor</command> + programs. The following configuration options are supported: + </para> + + <variablelist> + <title>Greeter Configuration Keys</title> + + <varlistentry> + <term>/apps/gdm/simple-greeter/banner_message_enable</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether the banner message text is displayed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/banner_message_text</term> + <listitem> + <synopsis>NULL (string)</synopsis> + <para> + Specifies the text banner message to show on the greeter + window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/disable_restart_buttons</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether to show the restart buttons in the login + window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/disable_user_list</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + If true, then the face browser with known users is not shown + in the login window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/logo_icon_name</term> + <listitem> + <synopsis>computer (string)</synopsis> + <para> + Set to the themed icon name to use for the greeter logo. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/recent-languages</term> + <listitem> + <synopsis>[] (string list)</synopsis> + <para> + Set to a list of languages to be shown by default in the login + window. Default value is "[]". With the default setting only + the system default language is shown and the option "Other..." + which pops-up a dialog box showing a full list of available + languages which the user can select. + </para> + + <para> + Users are not intended to change this setting by hand. Instead + GDM keeps track of any languages selected in this configuration + key, and will show them in the language combo box along with + the "Other..." choice. This way, commonly selected languages + are easier to select. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/recent-layouts</term> + <listitem> + <synopsis>[] (string list)</synopsis> + <para> + Set to a list of keyboard layouts to be shown by default in the + login panel. Default value is "[]". With the default setting + only the system default keyboard layout is shown and the option + "Other..." which pops-up a dialog box showing a full list of + available keyboard layouts which the user can select. + </para> + + <para> + Users are not intended to change this setting by hand. Instead + GDM keeps track of any keyboard layouts selected in this + configuration key, and will show them in the keyboard layout + combo box along with the "Other..." choice. This way, commonly + selected keyboard layouts are easier to select. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/wm_use_compiz</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether compiz is used as the window manager instead + of metacity. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="accessibilityconfiguration"> + <title>Accessibility Configuration</title> + + <para> + This section describes the accessibility configuration options available + in GDM. + </para> + + <sect3 id="accessibilitydialog"> + <title>GDM Accessibility Dialog And GConf Keys</title> + + <para> + The GDM greeter panel at the login screen displays an accessibility + icon. Clicking on that icon opens the GDM Accessibility Dialog. In + the GDM Accessibility Dialog, there is a list of checkboxes, so the + user can enable or disable the associated assistive tools. + </para> + + <para> + The checkboxes that correspond to the on-screen keyboard, screen + magnifier and screen reader assistive tools act on the three GConf + keys that are described in the next section of this document. By + enabling or disabling these checkboxes, the associated GConf key is + set to "true" or "false". When the GConf key is set to true, the + assistive tools linked to this GConf key are launched. When the + GConf key is set to "false", any running assistive tool linked to + this GConf key are terminated. These GConf keys are not automatically + reset to a default state after the user has logged in. Consequently, + the assistive tools that were running during the last GDM login + session will automatically be launched at the next GDM login session. + </para> + + <para> + The other checkboxes in the GDM Accessibility Dialog do not have + corresponding GConf keys because no additional program is launched to + provide the accessibility features that they offer. These other + options correspond to accessibility features that are provided by the + Xserver, which is always running during the GDM session. + </para> + </sect3> + + <sect3 id="accessibilitygconfconfiguration"> + <title>Accessibility GConf Keys</title> + + <para> + GDM offers the following GConf keys to control its accessibility + features: + </para> + + <variablelist> + <title>GDM Configuration Keys</title> + + <varlistentry> + <term>/desktop/gnome/interface/accessibility</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether the Accessibility infrastructure will be + started with the GDM GUI. This is needed for many + accessibility technology programs to work. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>/desktop/gnome/applications/at/screen_magnifier_enabled</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + If set, then the assistive tools linked to this GConf key will + be started with the GDM GUI program. By default this is a + screen magnifier application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>/desktop/gnome/applications/at/screen_keyboard_enabled</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + If set, then the assistive tools linked to this GConf key will + be started with the GDM GUI program. By default this is an + on-screen keyboard application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>/desktop/gnome/applications/at/screen_reader_enabled</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + If set, then the assistive tools linked to this GConf key will + be started with the GDM GUI program. By default this is a + screen reader application. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="accessibilitytoolsconfiguration"> + <title>Linking GConf Keys to Accessibility Tools</title> + + <para> + For the screen_magnifier_enabled, the screen_keyboard_enabled, and the + screen_reader_enabled GConf keys, the assistive tool which gets + launched depends on the desktop files located in the GDM autostart + directory as described in the "Autostart Configuration" section of + this manual. Any desktop file in the GDM autostart directory can be + linked to these GConf key via specifying that GConf key in the + AutostartCondition value in the desktop file. So the exact + AutostartCondition line in the desktop file could be one of the + following: + </para> + +<screen> +AutostartCondition=GNOME /desktop/gnome/applications/at/screen_keyboard_enabled +AutostartCondition=GNOME /desktop/gnome/applications/at/screen_magnifier_enabled +AutostartCondition=GNOME /desktop/gnome/applications/at/screen_reader_enabled +</screen> + + <para> + When an accessibility key is true, then any program which is linked to + that key in a GDM autostart desktop file will be launched (unless the + Hidden key is set to true in that desktop file). A single GConf key + can even start multiple assistive tools if there are multiple desktop + files with this AutostartCondition in the GDM autostart directory. + </para> + </sect3> + + <sect3 id="accessibilitytoolexample"> + <title>Example Of Modifying Accessibility Tool Configuration</title> + + <para> + For example, if GNOME is distributed with GOK as the default on-screen + keyboard, then this could be replaced with a different program if + desired. To replace GOK with the on-screen keyboard application + "onboard" and additionally activate the assistive tool "mousetweaks" + for dwelling support, then the following configuration is needed. + </para> + + <para> + Create a desktop file for onboard and a second one for mousetweaks; + for example, onboard.desktop and mousetweaks.desktop. These files + must be placed in the GDM autostart directory and be in the format + as explained in the "Autostart Configuration" section of this + document. + </para> + + <para> + The following is an example <filename>onboard.desktop</filename> file: + </para> + +<screen> +[Desktop Entry] +Encoding=UTF-8 +Name=Onboard Onscreen Keyboard +Comment=Use an on-screen keyboard +TryExec=onboard +Exec=onboard --size 500x180 -x 20 -y 10 +Terminal=false +Type=Application +StartupNotify=true +Categories=GNOME;GTK;Accessibility; +AutostartCondition=GNOME /desktop/gnome/applications/at/screen_keyboard_enabled +</screen> + + <para> + The following is an example <filename>mousetweaks.desktop</filename> + file: + </para> + +<screen> +[Desktop Entry] +Encoding=UTF-8 +Name=Software Mouse-Clicks +Comment=Perform clicks by dwelling with the pointer +TryExec=mousetweaks +Exec=mousetweaks --enable-dwell -m window -c -x 20 -y 240 +Terminal=false +Type=Application +StartupNotify=true +Categories=GNOME;GTK;Accessibility; +AutostartCondition=GNOME /desktop/gnome/applications/at/screen_keyboard_enabled +</screen> + + <para> + Note the line with the AutostartCondition that links both desktop + files to the GConf key for the on-screen keyboard. + </para> + + <para> + To disable GOK from starting, the desktop file for the GOK on-screen + keyboard must be removed or deactivated. Otherwise onboard and GOK + would simultaneously be started. This can be done by removing the + gok.desktop file from the GDM autostart directory, or by adding the + "Hidden=true" key setting to the gok.desktop file. + </para> + + <para> + After making these changes, GOK will no longer be started when the + user activates the on-screen keyboard in the GDM session; but onboard + and mousetweaks will instead be launched. + </para> + </sect3> + </sect2> + + <sect2 id="generalsessionconfig"> + <title>General Session Settings</title> +<!-- +<para> + TODO - I think this section should be expanded upon. What specific + keys are of interest, or would some users be likely to want + to configure? Also, would be good to be more specific about + how lock down management is handled. +</para> +--> + <para> + The GDM Greeter uses some of the same framework that your desktop + session will use. And so, it is influenced by a number of the same + GConf settings. For each of these settings the Greeter will use the + default value unless it is specifically overridden by a) GDM's + installed mandatory policy b) system mandatory policy. GDM installs + its own mandatory policy to lock down some settings for security. + </para> + </sect2> + + <sect2 id="gnomesettingsdaemon"> + <title>GNOME Settings Daemon</title> +<!-- +<para> + TODO - I think this section should be expanded upon. What specific + keys are of interest, or would some users be likely to want + to configure? Also, would be good to give a more complete + list of plugins that users might want to consider disabling. + Also, shouldn't we list the sound/active key in the Greeter + configuration setting? Oddly I do not find this key used + in anything but the chooser in SVN. +</para> +--> + + <para> + GDM enables the following gnome-settings-daemon plugins: + a11y-keyboard, background, sound, xsettings. + </para> + + <para> + These are responsible for things like the background image, font and + theme settings, sound events, etc. + </para> + + <para> + Plugins can also be disabled using GConf. For example, if you want to + disable the sound plugin then unset the following key: + <filename>/apps/gdm/simple-greeter/settings-manager-plugins/sound/active</filename>. + </para> + </sect2> + + <sect2 id="sessionconfig"> + <title>GDM Session Configuration</title> + + <para> + GDM sessions are specified using the FreeDesktop.org Desktop Entry + Specification, which can be referenced at the following URL: + <ulink url="http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec"> + http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec</ulink>. + </para> + + <para> + By default, GDM will install desktop files in the + <filename><share>/xsessions</filename> directory. GDM will + search the following directories in this order to find desktop files: + <filename><etc>/X11/sessions/</filename>, + <filename><dmconfdir>/Sessions</filename>, + <filename><share>/xsessions</filename>, and + <filename><share>/gdm/BuiltInSessions</filename>. By default the + <filename><dmconfdir></filename> is set to + <filename><etc>/dm/</filename> unless GDM is configured to use + a different directory via the "--with-dmconfdir" option. + </para> + + <para> + A session can be disabled by editing the desktop file and adding a line + as follows: <filename>Hidden=true</filename>. + </para> + + <para> + GDM desktop files support a GDM-specific extension, a key named + "X-GDM-BypassXsession". If the key is not specified in a + desktop file, the value defaults to "false". If this key is + specified to be "true" in a desktop file, then GDM will + launch the program specified by the desktop file "Exec" key + directly when starting the user session. It will not run the program + via the <filename><etc>/gdm/Xsession</filename> script, which is + the normal behavior. Since bypassing the + <filename><etc>/gdm/Xsession</filename> script avoids setting up + the user session with the normal system and user settings, sessions + started this way can be useful for debugging problems in the system or + user scripts that might be preventing a user from being able to start + a session. + </para> + + </sect2> + + <sect2 id="userconfig"> + <title>GDM User Session and Language Configuration</title> + <para> + The user's default session and language choices are stored in the + <filename>~/.dmrc</filename> file. When a user logs in for the first + time, this file is created with the user's initial choices. The user + can change these default values by simply changing to a different value + when logging in. GDM will remember this change for subsequent logins. + </para> + + <para> + The <filename>~/.dmrc</filename> file is in the standard + <filename>INI</filename> format. It has one section called + <filename>[Desktop]</filename> which has two keys: + <filename>Session</filename> and <filename>Language</filename>. + </para> + + <para> + The <filename>Session</filename> key specifies the basename of the + session <filename>.desktop</filename> file that the user wishes to + normally use without the <filename>.desktop</filename> extension. + The <filename>Language</filename> key specifies the language that the + user wishes to use by default. If either of these keys is missing, the + system default is used. The file would normally look as follows: + </para> + +<screen> +[Desktop] +Session=gnome +Language=cs_CZ.UTF-8 +</screen> + </sect2> + + </sect1> + + <!-- ============= GDM Commands ============================= --> + + <sect1 id="binaries"> + <title>GDM Commands</title> + + <sect2 id="sbindir_binaries"> + <title>GDM Root User Commands</title> + + <para> + The GDM package provides the following commands in + <filename>sbindir</filename> intended to be run by the root user: + </para> + + <sect3 id="gdmcommandline"> + <title><command>gdm</command> Command Line Options</title> + + <para> + <command>gdm</command> is the main daemon which sets up + graphical login environment and starts necessary helpers. + </para> + + <variablelist> + <title><command>gdm</command> Command Line Options</title> + + <varlistentry> + <term>-?, --help</term> + <listitem> + <para> + Gives a brief overview of the command line options. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--fatal-warnings</term> + <listitem> + <para> + Make all warnings cause GDM to exit. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--timed-exit</term> + <listitem> + <para> + Exit after 30 seconds. Useful for debugging. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--version</term> + <listitem> + <para> + Print the version of the GDM daemon. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="gdmrestartcommandline"> + <title><command>gdm-restart</command> Command Line Options</title> + + <para> + <command>gdm-restart</command> stops and restarts GDM by sending + the GDM daemon a HUP signal. This command will immediately terminate + all sessions and log out users currently logged in with GDM. + </para> + </sect3> + + <sect3 id="gdmsaferestartcommandline"> + <title><command>gdm-safe-restart</command> Command Line Options</title> + + <para> + <command>gdm-safe-restart</command> stops and restarts GDM by + sending the GDM daemon a USR1 signal. GDM will be restarted as soon + as all users log out. + </para> + </sect3> + + <sect3 id="gdmstopcommandline"> + <title><command>gdm-stop</command> Command Line Options</title> + + <para> + <command>gdm-stop</command> stops GDM by sending the GDM daemon + a TERM signal. + </para> + </sect3> + </sect2> + </sect1> + + <!-- ============= Troubleshooting =========================== --> + + <sect1 id="troubleshooting"> + <title>Troubleshooting</title> +<!-- +<para> + TODO - any other tips we should add? Might be useful to highlight any + common D-Bus configuration issues? +</para> +--> + + <para> + This section discusses helpful tips for getting GDM working. In general, + if you have a problem using GDM, you can submit a bug or send an email + to the gdm-list mailing list. Information about how to do this is in + the Introduction section of the document. + </para> + + <para> + If GDM is failing to work properly, it is always a good idea to include + debug information. To enable debugging, set the debug/Enable key to + "true" in the <filename><etc>/gdm/custom.conf</filename> + file and restart GDM. Then use GDM to the point where it fails, and + debug output will be sent to the system log file + (<filename><var>/log/messages</filename> or + <filename><var>/adm/messages</filename> depending on your Operating + System). If you share this output with the GDM community via a bug + report or email, please only include the GDM related debug information + and not the entire file since it can be large. If you do not see any + GDM syslog output, you may need to configure syslog (refer to the + <ulink type="help" url="man:syslog">syslog</ulink> man page). + </para> + + <sect2 id="wontstart"> + <title>GDM Will Not Start</title> + + <para> + There are a many problems that can cause GDM to fail to start, but + this section will discuss a few common problems and how to approach + tracking down a problem with GDM starting. Some problems will + cause GDM to respond with an error message or dialog when it tries + to start, but it can be difficult to track down problems when GDM + fails silently. + </para> + + <para> + First make sure that the Xserver is configured properly. The + GDM configuration file contains a command in the [server-Standard] + section that is used for starting the Xserver. Verify that this + command works on your system. Running this command from the + console should start the Xserver. If it fails, then the problem + is likely with your Xserver configuration. Refer to your Xserver + error log for an idea of what the problem may be. The problem may + also be that your Xserver requires different command-line options. + If so, then modify the Xserver command in the GDM configuration file + so that it is correct for your system. + </para> + + <para> + Also make sure that the <filename>/tmp</filename> directory has + reasonable ownership and permissions, and that the machine's file + system is not full. These problems will cause GDM to fail to start. + </para> + </sect2> + </sect1> + + <!-- ============= Application License ============================= --> + + <sect1 id="license"> + <title>License</title> + <para> + This program is free software; you can redistribute it and/or + modify it under the terms of the <ulink type="help" url="gnome-help:gpl"> + <citetitle>GNU General Public License</citetitle></ulink> as + published by the Free Software Foundation; + either version 2 of the License, or (at your option) any later + version. + </para> + <para> + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + <citetitle>GNU General Public License</citetitle> for more details. + </para> + <para> + A copy of the <citetitle>GNU General Public License</citetitle> is + included as an appendix to the <citetitle>GNOME Users + Guide</citetitle>. You may also obtain a copy of the + <citetitle>GNU General Public License</citetitle> from the Free + Software Foundation by visiting + <ulink type="http" url="http://www.fsf.org">their Web site</ulink> or by + writing to + <address> + Free Software Foundation, Inc. + <street>51 Franklin Street, Fifth Floor</street> + <city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode> + <country>USA</country> + </address> + </para> + </sect1> +</article> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> |