diff options
author | Ray Strode <rstrode@redhat.com> | 2008-09-01 13:57:04 +0000 |
---|---|---|
committer | Ray Strode <halfline@src.gnome.org> | 2008-09-01 13:57:04 +0000 |
commit | 7d9efad509bcd4293930424234c71d60bdcd9dcc (patch) | |
tree | df2048d7dde9273527ec390d9e12e43933747031 /docs/C | |
parent | c075a87b2e84d692e4cbb1283896da8c9d704f34 (diff) | |
download | gdm-7d9efad509bcd4293930424234c71d60bdcd9dcc.tar.gz |
Add Brian Cameron's initial cut at the docs.
2008-09-01 Ray Strode <rstrode@redhat.com>
* docs/*, configure.ac, Makefile.am:
Add Brian Cameron's initial cut at the docs.
svn path=/trunk/; revision=6451
Diffstat (limited to 'docs/C')
-rw-r--r-- | docs/C/gdm.xml | 2175 | ||||
-rw-r--r-- | docs/C/legal.xml | 76 |
2 files changed, 2251 insertions, 0 deletions
diff --git a/docs/C/gdm.xml b/docs/C/gdm.xml new file mode 100644 index 00000000..b701c971 --- /dev/null +++ b/docs/C/gdm.xml @@ -0,0 +1,2175 @@ +<?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.24.0"> + <!ENTITY date "08/27/2008"> + <!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-08</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 role="maintainer"> + <firstname>Brian</firstname><surname>Cameron</surname> + <affiliation> + <address><email>Brian.Cameron@Sun.COM</email></address> + </affiliation> + </author> + </authorgroup> + <copyright> + <year>1998</year> + <year>1999</year> + <holder>Martin K. Petersen</holder> + </copyright> + <copyright> + <year>2001</year> + <year>2003</year> + <year>2004</year> + <holder>George Lebl</holder> + </copyright> + <copyright> + <year>2003</year> + <holder>Red Hat, Inc.</holder> + </copyright> + <copyright> + <year>2003</year> + <year>2004</year> + <year>2005</year> + <year>2006</year> + <year>2007</year> + <year>2008</year> + <holder>Sun Microsystems, Inc.</holder> + </copyright> + + &legal; + + <releaseinfo> + This manual describes version &version; of the GNOME Display Manager. + It was last updated on &date;. + </releaseinfo> + </articleinfo> + + <!-- ============= 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>gdmchooser</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 (<command>gdmlogin</command> or + <command>gdmgreeter</command>). + </para> + + <para> + PAM - Pluggable Authentication Mechanism + </para> + + <para> + XDMCP - X Display Manage Protocol + </para> + + <para> + Xserver - An implemention of the X Window System. For example the + Xorg webserver 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://www.gnome.org/projects/gdm/"> + http://www.gnome.org/projects/gdm</ulink> and the project + Wiki <ulink type="http" url="http://live.gnome.org/GDM"> + http://live.gnome.org/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 + many configuration options are no longer supported. + </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> + </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> + 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. + </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 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. + </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 "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> + TODO - Is this a complete list of applets? Would be nice to provide + a paragraph to explain each available one, and what they do. + On Solaris, only the a11y and power applet are available, so + I'm probably not the best person to document this. +</para> +--> + + <para> + The GDM greeter program displays a panel at the bottom of the screen + which provides additional functionalities. There is a button to launch + accessibility programs, and a number of applets which may be displayed + or not depending on configuration. These include a power management + applet to show the laptop battery status and a keyboard switching + applet which allows users to specify alternative keyboard layouts. + Some applets may not be available on all distributions. 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 Solaris) to require the + user have appropriate authorization before accepting the shutdown or + restart request. + </para> + </sect2> + + <sect2 id="accessibility"> + <title>Accessibility</title> + +<para> + TODO - Is there detail I am missing? +</para> + + <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 change the theme to an accessible theme, such + as High Contrast, if needed. + </para> + + <para> + There is a button on the left side of the GDM panel left which can be + used to start the various accessibility features found in GDM. Refer + to the "Configuration" section to learn about Greeter + configuration keys used to start accessibility features by default + when GDM is started. + </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> + 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. +</para> +--> + + <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 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. + </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 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 user home + directories can be a very time-consuming task. Since it not + practical to load images over NIS or NFS, GDM does not attempt to + load face images from remote home directories. Furthermore, GDM will + give up loading face images after 5 seconds of activity and will + only display the users whose pictures it has gotten so far. The + <filename>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. + To work around such problems, it is recommended to place face images + in the directory specified by the <filename>GlobalFaceDir</filename> + configuration option. + </para> + + <para> + 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. + </para> + + <para> + 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. + </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 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. This can be enabled by starting the GDM daemon + with the "--debug" option. + </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> + 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? +</para> +--> + + <para> + The output from the user session is redirected to + <filename>~/.xsession-errors</filename> + before even the <filename>PreSession</filename> script is started. So + it is not 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. + </para> + + <para> + You can suppress the 10 second warning by returning code 66 from the + <filename>Xsession</filename>script or from your session binary (the + default <filename>Xsession</filename> script propagates those codes + back). This is useful if you have some sort of special logins for + which it is not an error to return less then 10 seconds later, or if + you setup the session to already display some error message and the + GDM message would be confusing and redundant. + </para> + + <para> + The session output is piped through the GDM daemon, so the + <filename>~/.xsession-errors</filename> 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. + </para> + + <para> + Note that if GDM can not open this file for some reason, then a + fallback file will be created in the <filename>/tmp</filename> + directory named <filename>/tmp/xses-<user>.XXXXXX</filename> + where the <filename>XXXXXX</filename> are some random characters. + </para> + + <para> + Note that the <filename>~/.xsession-errors</filename> and + <filename>/tmp/xses-XXXXXX</filename> 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. + </para> + </sect2> + + <sect2 id="fusa"> + <title>Fast User Switch Applet (FUSA)</title> + +<!-- +<para> + TODO - Add a section about the Fast User Switch Applet +</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>/lib/gdm</filename> directory. The + <filename><var>/lib/gdm</filename> directory should have + root:gdm ownership and 1770 permissions to ensure only the + "gdm" user has access to these files. + </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 or perform a denial-of-service attack on that session. 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 to 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 session: + </para> + +<screen> + gdm-autologin session required pam_unix_session.so.1 +</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="nfssecurity"> + <title>GDM Security With NFS</title> + +<!-- +<para> + TODO - Need to update, we changed how Xauth is handled so this section + is probably wrong. +</para> +--> + + <para> + Note that NFS traffic really goes "over the wire" and thus + can be snooped unless it is tunneled through a secure channel like ssh. + When accessing the user's X authorization file + (<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 + <filename>[security]</filename> section to false. + </para> + </sect2> + + <sect2 id="xauth"> + <title>X Server Authentication Scheme</title> + +<!-- +<para> + TODO - I believe how Xauth is handled changed a bit, so is the below + still correct? +</para> +--> + + <para> + The Xserver authorization directory + (<filename><var>/lib/gdm</filename>) is used to store 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 Xauth files + from this directory. + </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. + </para> + +<!-- +<para> + TODO - is the below still true? +</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. So be careful about using + remote X display. + </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 is a + reasonably secure way to use XDMCP. + </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 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 using over the net, 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> + + </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, 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 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> + + <sect2 id="fileaccess"> + <title>Accessing Files</title> + +<!-- +<para> + TODO - Looking at the code, we now just call g_key_file_load_from_file + when loading files from the user's $HOME directory. Is this + a bug? Should we be doing some checking to make sure files + we open are not links, sockets or devices, etc.? Or was this + just over-engineered before and we should just drop this part + of the documentation? + TODO - I am not really clear on how GDM manages the Xsession file + anymore. Someone who understands this should explain. + TODO - Is there still a maximum file size or other things that should + be explained about how face images are now accessed? + + Perhaps this section should just go away? +</para> +--> + + <para> + In general GDM is very reluctant regarding reading/writing of user + files (such as the <filename>~/.dmrc</filename>, + <filename>~/.face</filename>, + <filename>~/.xsession-errors</filename>, and + <filename>~/.Xauthority</filename> files). For instance it refuses to + access anything but regular files. Links, sockets and devices are + ignored. The value of the <filename>RelaxPermissions</filename> + parameter determines whether GDM should accept files writable by the + user's group or others. These are ignored by default. + </para> + +<-- +<para> + TODO - UserAuthFBDir is not correct anymore. Need to fix. +</para> +--> + + <para> + All operations on user files are done with the effective user id of the + user. If the sanity check fails on the user's + <filename>.Xauthority</filename> file, a fallback cookie is created in + the directory specified by the <filename>UserAuthFBDir</filename> + configuration setting (<filename>/tmp</filename> by default). + </para> + + <para> + Finally, the sysadmin can specify the maximum file size 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> + </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 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> + + <!-- ============= 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 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 has been successfully started, 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 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> + 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> + 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 the user terminates his 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> + 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="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 + supports 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> + + <para> + Since many systems reset the language selections done by GDM, GDM will + set the <filename>$GDM_LANG</filename> variable to the selected + language. You can use this to reset the language environmental + variables after you run the user's profile. If the user elected to use + the system language, then <filename>$GDM_LANG</filename> is not set. + </para> + + <para> + The <filename>Xsession</filename> script will set the + <filename>$DESKTOP_SESSION</filename> environment variable to the + basename of the session that the user selected, without the + <filename>.desktop</filename> extension. You can use this to run + any specific code for a given session. For backwards compatibility + the <filename>$GDMSESSION</filename> environment variable is also set + to the same value. + </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 GConf + 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 + standard <filename>INI</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 <filename>/etc/gdm/custom.conf</filename> supports the + "[daemon]", "[security]l", 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> + +<!-- +<para> + TODO - What about automatic login? Is this just now timedlogin with + a 0 timeout value or something? Need to discuss this. +</para> +--> + + <sect3 id="daemonsection"> + <variablelist> + <title>[daemon]</title> + + <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> + + <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> + TODO - Is the root user still not available for this feature? +</para> +--> + + <para> + This is the user that should be logged in after a specified + number of seconds of inactivity. This can never be + "root" and gdm will refuse to log in root this way. + The same features as for <filename>AutomaticLogin</filename> + are supported. The same control chars and piping to a + application are supported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>TimedLoginDelay</term> + <listitem> + <synopsis>TimedLoginDelay=30</synopsis> +<!-- +<para> + TODO - Is the 10 second delay still true? +</para> +--> + <para> + Delay in seconds before the <filename>TimedLogin</filename> + user will be logged in. It must be greater then or equal to + 10. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User</term> + <listitem> + <synopsis>User=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> + </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>EnableProxy</term> + <listitem> + <synopsis>EnableProxy=false</synopsis> + <para> + Setting this to true enables support for running XDMCP sessions + on a local proxy Xserver. This may improve the performance of + XDMCP sessions, especially on high latency networks, as many + X protocol operations can be completed without going over the + network. + </para> + + <para> + Note, however, that this mode will significantly increase the + burden on the machine hosting the XDMCP sessions + </para> + + <para> + See the <filename>FlexiProxy</filename> and + <filename>FlexiProxyDisconnect</filename> options for further + details on how to configure support for this feature. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>HonorIndirect</term> + <listitem> + <synopsis>HonorIndirect=true</synopsis> + <para> + Enables XDMCP INDIRECT choosing (i.e. remote execution of + <filename>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>MaxPendingIndirect</term> + <listitem> + <synopsis>MaxPendingIndirect=4</synopsis> + <para> + GDM will only provide <filename>MaxPendingIndirect</filename> + displays with host choosers simultaneously. If more queries + from different hosts come in, the oldest ones will be + forgotten. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MaxSessions</term> + <listitem> + <synopsis>MaxSessions=16</synopsis> + <para> + Determines the maximum number of remote display connections + which will be managed simultaneously. I.e. the total number of + remote displays that can use your host. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MaxWait</term> + <listitem> + <synopsis>MaxWait=30</synopsis> + <para> + When GDM is ready to manage a display an ACCEPT packet is sent + to it containing a unique session id which will be used in + future XDMCP conversations. + </para> + + <para> + GDM will then place the session id in the pending queue + waiting for the display to respond with a MANAGE request. + </para> + + <para> + If no response is received within MaxWait seconds, GDM will + declare the display dead and erase it from the pending queue + freeing up the slot for other displays. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>MaxWaitIndirect</term> + <listitem> + <synopsis>MaxWaitIndirect=30</synopsis> + <para> + The MaxWaitIndirect parameter determines the maximum number of + seconds between the time where a user chooses a host and the + subsequent indirect query where the user is connected to the + host. When the timeout is exceeded, the information about the + chosen host is forgotten and the indirect slot freed up for + other displays. The information may be forgotten earlier if + there are more hosts trying to send indirect queries then + <filename>MaxPendingIndirect</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Port</term> + <listitem> + <synopsis>Port=177</synopsis> + <para> + The UDP port number <filename>gdm</filename> should listen to + for XDMCP requests. Do not change this unless you know what + you are doing. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>PingIntervalSeconds</term> + <listitem> + <synopsis>PingIntervalSeconds=15</synopsis> + <para> + Interval in which to ping the Xserver in seconds. If the + Xserver does not return before the next time we ping it, the + connection is stopped and the session ended. This is a + combination of the XDM PingInterval and PingTimeout, but in + seconds. + </para> + + <para> + Note that GDM in the past used to have a + <filename>PingInterval</filename> configuration key which was + also in minutes. For most purposes you'd want this setting + to be lower then one minute however since in most cases where + XDMCP would be used (such as terminal labs), a lag of more + than 15 or so seconds would really mean that the terminal was + turned off or restarted and you would want to end the session. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ProxyReconnect</term> + <listitem> + <synopsis>FlexiProxyReconnect=</synopsis> + <para> + Setting this option enables experimental support for session + migration with XDMCP sessions. This enables users to disconnect + from their session and later reconnect to that same session, + possibly from a different terminal. + </para> + + <para> + In order to use this feature, you must have a nested Xserver + available which supports disconnecting from its parent Xserver + and reconnecting to another Xserver. Currently, the Distributed + Multihead X (DMX) server supports this feature to some extent + and other projects like NoMachine NX are busy implementing it. + </para> + + <para> + This option should be set to the path of a command which will + handle reconnecting the XDMCP proxy to another backend display. + A sample implementation for use with DMX is supplied. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ProxyXServer</term> + <listitem> + <synopsis>ProxyXServer=</synopsis> + <para> + The Xserver command line for a XDMCP proxy. Any nested X + server like Xnest, Xephyr or Xdmx should work fairly well. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Willing</term> + <listitem> + <synopsis>Willing=<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> + TODO - I only see the a11y keys being used in the chooser code, + not the greeter code. Is this an error? +</para> +--> + + <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/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/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_accessibility_button</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether to show the accessibility buttons in the login + window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/disable_accessibility_button</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether to show the accessibility buttons in the login + window. + </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> + + <varlistentry> + <term>/apps/gdm/simple-greeter/accessibility/screen_keyboard_enabled</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether the on-screen keyboard accessibility + application is started by default with the login greeter. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/accessibility/screen_reader_enabled</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether the screen reader accessibility application is + started by default with the login greeter. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/apps/gdm/simple-greeter/accessibility/screen_magnifier_enabled</term> + <listitem> + <synopsis>false (boolean)</synopsis> + <para> + Controls whether the screen magnifier accessibility application + is started by default with the login greeter. + </para> + </listitem> + </varlistentry> + </variablelist> + </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 type="http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec"> + http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec</ulink>. + </para> + + <para> + These files are installed, by default, to + <filename><etc>/X11/sessions/</filename>. For backwards + compatibility any desktop files in the + <filename><etc>/Sessions</filename>, + <filename><share>/xsessions</filename>, and + <filename><share/gdm/BuiltInSessions</filename> directories are also recognized by GDM. + </para> +<!-- +<para> + TODO - I do not think the following disabling feature works in GDM + anymore. Should it? +</para> +--> + <para> + A session can be disabled by editing the desktop file and adding a line + that says <filename>Hidden=true</filename>. + </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 notice this and prompt the user if they want + to change their saved default value or not. + </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="bindir_binaries"> + <title>GDM User Commands</title> + + <para> + The GDM package provides the following commands in + <filename>bindir</filename> intended to be used by the end-user: + </para> + + <sect3 id="gdmscreenshot"> + <title><command>gdm-screenshot</command> Command Line Options</title> +<!-- +<para> + TODO - Provide more information about how to use this. +</para> +--> + <para> + The <command>gdm-screenshot</command> command is a utility to take + a screenshot of the GDM login screen. + </para> + + <variablelist> + <title><command>gdm</command> and <command>gdm-binary</command> + Command Line Options</title> + + <varlistentry> + <term>-?, --help</term> + <listitem> + <para> + Gives a brief overview of the command line options. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--debug</term> + <listitem> + <para> + Show debug output. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <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> and <command>gdm-binary</command> + Command Line Options</title> + + <para> + The <command>gdm</command> command is really just a script which + runs the <command>gdm-binary</command>, passing along any options. + Before launching <command>gdm-binary</command>, the gdm wrapper + script will source the <filename><etc>/profile</filename> file + to set the standard system environment variables. In order to better + support internationalization, it will also set the LC_MESSAGES + environment variable to LANG if neither LC_MESSAGES or LC_ALL are + set. The <command>gdm-binary</command> is the actual GDM daemon. + </para> + + <variablelist> + <title><command>gdm</command> and <command>gdm-binary</command> + Command Line Options</title> + + <varlistentry> + <term>-?, --help</term> + <listitem> + <para> + Gives a brief overview of the command line options. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--debug</term> + <listitem> + <para> + Print debug output to the syslog. This is typically + <filename><var>/log/messages</filename> or + <filename><var>/adm/messages</filename> depending on + your Operating System. + </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 turn on debug, launch gdm with the --debug + option. Then use GDM to the point where it fails, and debug output will + be sent to your system log + (<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: +--> diff --git a/docs/C/legal.xml b/docs/C/legal.xml new file mode 100644 index 00000000..ac97e1de --- /dev/null +++ b/docs/C/legal.xml @@ -0,0 +1,76 @@ + <legalnotice id="legalnotice"> + <para> + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License (GFDL), Version 1.1 or any later version published + by the Free Software Foundation with no Invariant Sections, + no Front-Cover Texts, and no Back-Cover Texts. You can find + a copy of the GFDL at this <ulink type="help" + url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS + distributed with this manual. + </para> + <para> This manual is part of a collection of GNOME manuals + distributed under the GFDL. If you want to distribute this + manual separately from the collection, you can do so by + adding a copy of the license to the manual, as described in + section 6 of the license. + </para> + + <para> + Many of the names used by companies to distinguish their + products and services are claimed as trademarks. Where those + names appear in any GNOME documentation, and the members of + the GNOME Documentation Project are made aware of those + trademarks, then the names are in capital letters or initial + capital letters. + </para> + + <para> + DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED + UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE + WITH THE FURTHER UNDERSTANDING THAT: + + <orderedlist> + <listitem> + <para>DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR + IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES + THAT THE DOCUMENT OR MODIFIED VERSION OF THE + DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR + A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE + RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE + OF THE DOCUMENT OR MODIFIED VERSION OF THE + DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR + MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, + YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY + CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY + SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER + OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS + LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED + VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER + EXCEPT UNDER THIS DISCLAIMER; AND + </para> + </listitem> + <listitem> + <para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL + THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), + CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, + INITIAL WRITER, ANY CONTRIBUTOR, OR ANY + DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION + OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH + PARTIES, BE LIABLE TO ANY PERSON FOR ANY + DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR + CONSEQUENTIAL DAMAGES OF ANY CHARACTER + INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS + OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR + MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR + LOSSES ARISING OUT OF OR RELATING TO USE OF THE + DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, + EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF + THE POSSIBILITY OF SUCH DAMAGES. + </para> + </listitem> + </orderedlist> + </para> + </legalnotice> + |