<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [
  <!ENTITY kappname "&kdm;">
  <!ENTITY package "kdebase">
  <!ENTITY kdmrc "<filename>kdmrc</filename>">
  <!ENTITY XDMCP "<acronym>XDMCP</acronym>">
  <!ENTITY xdm "<application>xdm</application>">
  <!ENTITY kdmrc-ref SYSTEM "kdmrc-ref.docbook">
  <!ENTITY % addindex "INCLUDE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">
<bookinfo>
<title>The &kdm; Handbook</title>

<authorgroup>
<author>
&Oswald.Buddenhagen; &Oswald.Buddenhagen.mail;
</author><!-- 
<othercredit role="developer">
&Oswald.Buddenhagen; &Oswald.Buddenhagen.mail;
<contrib>Developer</contrib>
</othercredit>
<othercredit role="reviewer">
&Lauri.Watts; &Lauri.Watts.mail;
<contrib>Reviewer</contrib>
</othercredit> -->

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2000</year>
<holder>&Neal.Crook;</holder>
</copyright>

<copyright>
<year>2002</year>
<holder>&Oswald.Buddenhagen;</holder>
</copyright>

<copyright>
<year>2003</year>
<holder>&Lauri.Watts;</holder>
</copyright>

<date>2003-03-01</date>
<releaseinfo>0.05.02</releaseinfo>

<abstract>
<para>This document describes &kdm; the &kde; Display Manager. &kdm;
is also known as the <quote>Login Manager</quote>.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdm</keyword>
<keyword>xdm</keyword>
<keyword>display manager</keyword>
<keyword>login manager</keyword>
</keywordset>
</bookinfo>

<!-- ********************************************************************** -->  
<chapter id="introduction">
<title>Introduction</title>

<para> &kdm; provides a graphical interface that allows you to log in
to a system. It prompts for login (username) and password,
authenticates the user and starts a <quote>session</quote>.  &kdm; is
superior to &xdm;, the X Display Manager, in
a number of ways.</para>

</chapter>

<!-- Chapters to write -->
<!-- * Just enough config to get it to run and login to KDE 
     * Adding more session types (GNOME, etc)
     * Adding other customizations to XSession (ssh/gpg-agent, etc)
     * Further customization to KDM (via the kcontrol module, and by 
       hand)
     * XDMCP by query
     * XDMCP by broadcast
     * Sound transparency (if Ade can tell me how!)
     * Document all Keys in the Config File
     * Pull in all options from the KControl Module
     * More resources
-->

<chapter id="quickstart">
<title>Quick Start Guide</title>

<para>This is a quick start guide for users who fit the following
pattern:</para>

<itemizedlist>
<listitem>
<para>X is configured and works with the command
<command>startx</command> from the commandline.</para>
</listitem>
<listitem>
<para>Each user will generally only use a single window manager or
desktop environment, and does not change this choice very
often, or is comfortable editing a single text file in order to change
their choice.</para>
</listitem>
</itemizedlist>

<para>This scenario will be sufficient for many environments where a
single user or several users normally boot the computer and log into
their preferred environment.</para>

<procedure>
<title>Setting up a Default Session</title>
<step>
<para>Create or open the file <filename>~/.xinitrc</filename></para>
<para>If you already have a working <filename>~/.xinitrc</filename>,
go to the next step</para>
</step>
<step>
<para>If one does not already exist, add a line to the
<filename>~/.xinitrc</filename> to start your preferred window manager
or desktop environment.</para>
<para>For &kde; you should enter:</para>
<screen><userinput>startkde</userinput></screen>
<para>For other window managers or desktop environments, you should
look in their documentation for the correct command.</para>
</step>
<step><para>Make a link as follows:</para>
<screen><userinput><command>ln</command> <option>-s</option> <parameter>~/.xinitrc ~/.xsession</parameter></userinput></screen>
</step>
</procedure>

<para>At this point, typing
<userinput><command>startx</command></userinput> on the commandline
should start X, with a &kde; session.  The next task is to try
&kdm;.</para>

<para>As <systemitem class="username">root</systemitem>, type
<userinput><command>kdm</command></userinput> at the prompt.</para>

<para>You should see a login window, which is described more fully
in<xref linkend="login" />.</para>

<para>Typing your normal username and password in the fields provided,
and leaving <option>default</option> selected as the session type
should now open a &kde; session for your user.</para>

<para>If you have other users to configure, you should repeat the
procedure above for each of them.</para>

<note>
<para>This is a quick guide to getting up and running only.  You
probably will want to customize &kdm; further, for example, to hide
the names of the system accounts, to allow further sessions, and much
more.  Please read through the rest of this manual to find out how to
do these things.</para>
</note>

</chapter>

<chapter id="login"> 
<title>The Login Window</title> 

<para> The user interface to &kdm; consists of two dialog boxes. 
The main dialog box has these controls:</para>

<itemizedlist> 
<listitem>
<para>A <guilabel>Username:</guilabel> field for you to enter your
username.</para>
</listitem>

<listitem>
<para>A <guilabel>Password:</guilabel> field for you to enter your
password.</para>
</listitem>

<listitem>
<para>(Optionally) a graphical image of each user (for example, a
digitized photograph). Clicking on an image is equivalent to typing
the associated username into the <guilabel>Username:</guilabel>
field. (This feature is an imitation of the login box on
IRIX).</para> </listitem>

<listitem>
<para>A <guilabel>Menu</guilabel> drop-down box that allows
&kdm; to be used to start sessions with various different window managers or
desktop environments installed on the system.</para>
</listitem>

<listitem>
<para>(Optionally) a region to the right of the
<guilabel>Username:</guilabel>, <guilabel>Password:</guilabel> and
<guilabel>Session Type:</guilabel> fields which can be used to display
either a static image or an analog clock.</para>
</listitem>

<listitem>
<para>A <guibutton>Login</guibutton> button that validates the
username/password combination and attempts to start a session of the
selected type.</para> 
</listitem>

<listitem>
<para>A <guibutton>Clear</guibutton> button that clears the text from
the <guilabel>Login</guilabel> and <guilabel>Pass</guilabel>
fields.</para>
</listitem> 

<listitem>
<para>(Optionally) A <guibutton>Shutdown</guibutton> button that
displays the <guibutton>Shutdown</guibutton> dialog box.</para>
</listitem>
<listitem>
<para>A <guibutton>Menu</guibutton> button that opens an action menu
with the following items:</para>
 
<itemizedlist>
<listitem>
<para>(On local displays) a <guimenuitem>Restart X
Server</guimenuitem> item that terminates the currently running
&X-Server;, starts a new one and displays the login dialog again. You
can use this if the display content seems to be broken somehow.</para>
</listitem>

<listitem>
<para>(On remote displays) A <guimenuitem>Close
Connection</guimenuitem> item that closes the connection to the XDMCP
server you are currently connected to. If you got to this server
through a host chooser, this will bring you back to the chooser,
otherwise it will only reset the &X-Server; and bring up the login
dialog again.</para>
</listitem>

<listitem>
<para>(Optionally on local displays) A <guimenuitem>Console
Mode</guimenuitem> item that terminates the currently running
&X-Server; and leaves you alone with a console login. &kdm; will
resume the graphical login if nobody is logged in at the console for
some time. To make this work, you need to use the
local@&lt;console&gt; syntax in the <filename>Xservers</filename>
file (see comments in that file).</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>(Optionally) A <guibutton>Shutdown...</guibutton> button that
displays the shutdown dialog box.</para>
</listitem>
</itemizedlist>

<para>The <guilabel>Shutdown</guilabel> dialog box presents a set of
radio buttons that allow one of these options to be selected:</para>

<variablelist>
<varlistentry>
<term>Shutdown</term>
<listitem><para>Shut the system down in a controlled manner,
ready for power-down.</para></listitem>
</varlistentry>
<varlistentry>
<term>Restart</term>
<listitem><para>Shut the system down and reboot. For systems that use
<application>Lilo</application>, an optional drop-down box allows you to select
a particular operating-system kernel to be used for the
reboot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Restart X Server</term> 
<listitem>
<para>Stop and then restart the X-server. Typically, you might need to
use this option if you have changed your X11 configuration in some
way.</para>
</listitem> 
</varlistentry>
<varlistentry>
<term>Console Mode</term>
<listitem>
<para>Stop the &X-Server; and return the system to console mode. This is
achieved by bringing the system down to run-level 3. Typically, the system
manager might need to use this option before upgrading or re-configuring X11
software.</para>
</listitem> 
</varlistentry>
</variablelist>

<para>Pressing the <guibutton>OK</guibutton> button initiates the
selected action; pressing the <guibutton>Cancel</guibutton> button
returns to the main &kdm; dialog box. </para>

</chapter>

<!-- *********************************************************************** -->
<chapter id="configuring-kdm">
<title>Configuring &kdm;</title>

<para>This chapter assumes that &kdm; is already up and running on
your system, and that you simply want to change its behavior in some
way.</para>

<para>When &kdm; starts up, it reads its configuration from the
folder <filename
class="directory">$KDEDIR/share/config/kdm/</filename> (this may be
<filename class="directory">/etc/kde3/kdm/</filename> or something
else on your system).</para>

<para>The main configuration file is &kdmrc;; all other files are
referenced from there and could be stored under any name anywhere on
the system - but usually that would not make much sense for obvious
reasons (one particular exception is referencing configuration files
of an already installed &xdm; - however when a new &kdm; is installed,
it will import settings from those files if it finds an already installed
&xdm;).</para>

<para>Since &kdm; must run before any user is logged in, it is not
associated with any particular user. Therefore, it is not possible to have
user-specific configuration files; all users share the common &kdmrc;.  It
follows from this that the configuration of &kdm; can only be altered by
those users that have write access to
<filename>$<envar>KDEDIR</envar>/share/config/kdm/kdmrc</filename> (normally
restricted to system administrators logged in as <systemitem
class="username">root</systemitem>).</para>

<para>You can view the &kdmrc; file currently in use on your system, and you
can configure &kdm; by editing this file. Alternatively, you can use the
graphical configuration tool provided by the &kcontrolcenter; (under
<menuchoice><guisubmenu>System Administration</guisubmenu><guimenuitem>Login
Manager</guimenuitem></menuchoice>), which is described in <ulink
url="help:/kcontrol/login-manager.html">the &kcontrol; help files</ulink>.
</para>

<para>The remainder of this chapter describes configuration of &kdm;
via the &kcontrol; module, and the <link linkend="kdm-files">next
chapter</link> describes the options available in &kdmrc; itself. If
you only need to configure for local users, the &kcontrol; module
should be sufficient for your needs.  If you need to configure remote
logins, or have multiple &kdm; sessions running, you will need to read
on.</para>

<sect1 id="kdm-kcontrol-module">
<sect1info>
<authorgroup>
<author>&Thomas.Tanghus; &Thomas.Tanghus.mail;</author>
<author>&Steffen.Hansen; &Steffen.Hansen.mail;</author>
<author>&Mike.McBride; &Mike.McBride.mail;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
</sect1info>

<title>The Login Manager &kcontrol; Module</title>

<para>Using this module, you can configure the &kde; graphical login
manager, &kdm;.  You can change how the login screen looks, who has
access using the login manager and who can shutdown the
computer.</para>

<note><para>All settings will be written to the configuration file
&kdmrc;, which in it's original state has many comments to help you
configure &kdm;.  Using this &kcontrol; module will strip these
comments from the file.  All available options in &kdmrc; are covered
in <xref linkend="kdm-files"/>.</para>

<para>The options listed in this chapter are cross referenced with
their equivalents in &kdmrc;. All options available in the &kcontrol;
module are also available directly in &kdmrc; but the reverse is not
true.</para></note>

<para>In order to organize all of these options, this module is
divided into several sections: <link
linkend="kdmconfig-appearance"><guilabel>Appearance</guilabel></link>,
<link linkend="kdmconfig-font"><guilabel>Font</guilabel></link>, <link
linkend="kdmconfig-background"><guilabel>Background</guilabel></link>,
<link
linkend="kdmconfig-shutdown"><guilabel>Shutdown</guilabel></link>,
<link linkend="kdmconfig-users"><guilabel>Users</guilabel></link> and
<link
linkend="kdmconfig-convenience"><guilabel>Convenience</guilabel></link>.</para>

<para>You can switch between the sections using the tabs at the top of
the window.</para>

<note><para>If you are not currently logged in as a superuser, you
will need to click the <guibutton>Administrator Mode</guibutton>
Button. You will then be asked for a superuser password.  Entering a
correct password will allow you to modify the settings of this
module.</para></note>

<sect2 id="kdmconfig-appearance">
<title>Appearance</title>

<para>From this page you can change the visual appearance of &kdm;,
&kde;'s graphical login manager.</para>

<para>The <guilabel>Greeting:</guilabel> is the title of the login
 screen.  Setting this is especially useful if you have many servers users
 may log in to.  You may use various placeholders, which are described
 along with the corresponding key
 <link linkend="option-greetstring"><option>GreetString</option></link>
 in &kdmrc;.
</para>

<para>You can then choose to show either the current system time, a logo or
nothing special in the login box.  Make your choice in the radio buttons
labeled <guilabel>Logo area:</guilabel>. This corresponds to <link
linkend="option-logoarea"><option>LogoArea</option></link> in &kdmrc;</para>

<para>If you chose <guilabel>Show logo</guilabel> you can now choose a
logo:</para>

<itemizedlist>
<listitem>
<para>Drop an image file on the image button.</para>
</listitem>
<listitem>
<para>Click on the image button and select a new image from the image chooser
dialog.</para>
</listitem>
</itemizedlist>

<para>If you do not specify a logo the default
<filename>$<envar>KDEDIR</envar>/share/apps/kdm/pics/kdelogo.xpm</filename>
will be displayed.</para>

<para>Normally the login box is centered on the screen.  Use the
<guilabel>Position:</guilabel> options if you want it to appear
elsewhere on the screen.  You can specify the relative position
(percentage of the screen size) for the center of the login window,
relative to the top left of the display, in the fields labelled
<guilabel>X:</guilabel> and <guilabel>Y:</guilabel> respectively.
These correspond to the key
<link linkend="option-greeterpos"><option>GreeterPos</option></link>
in &kdmrc;.</para>

<para>While &kde;'s style depends on the settings of the user logged
in, the style used by &kdm; can be configured using the <guilabel>GUI
Style:</guilabel> and <guilabel>Color Scheme:</guilabel> options.
These correspond to the keys <link
linkend="option-guistyle"><option>GUIStyle</option></link> and <link
linkend="option-colorscheme"><option>ColorScheme</option></link> in
&kdmrc; respectively.</para>

<para>Below that, you have a dropdown box to choose the language for
your login box, corresponding to setting <option>Language</option> in
&kdmrc;.</para>

</sect2>

<sect2 id="kdmconfig-font">
<title>Font</title>

<para>From this section of the module you can change the fonts used in the
login window.  Only fonts available to all users are available here, not
fonts you have installed on a per user basis.</para>

<para>You can select three different font styles from the drop down box
(<guilabel>General:</guilabel>, <guilabel>Failures:</guilabel>,
<guilabel>Greeting</guilabel>).  When you click on the
<guibutton>Choose...</guibutton> button a dialog appears from which you can
select the new characteristics for the font style.</para>

<itemizedlist>
<listitem>
<para>The <guilabel>General:</guilabel> font is used in all other places in the
login window.</para>
</listitem>
<listitem>
<para>The <guilabel>Failures:</guilabel> font is used when a login
fails.</para>
</listitem>
<listitem>
<para>The <guilabel>Greeting:</guilabel> font is the font used for the title
(Greeting String).</para>
</listitem>
</itemizedlist>

<para>You can also check the box labelled <guilabel>User anti-aliasing for
fonts</guilabel> if you want smoothed fonts in the login dialog.</para>

<para>An example of each font can be seen in the
<guilabel>Example</guilabel> Box.</para>

</sect2>

<sect2 id="kdmconfig-background">
<title>Background</title>

<para>Here you can change the desktop background which will be displayed
before a user logs in. You can have a single color or an image as a
background. If you have an image as the background and select center, the
selected background color will be used around the image if it is not
large enough to cover the entire desktop.</para>

<para>The background colors and effects are controlled by the options on
the tab labeled <guilabel>Background</guilabel> and you select a
background image and its placement from the options on the tab labeled
<guilabel>Wallpaper</guilabel>.</para>

<para>To change the default background color(s) simply click either of
the color buttons and select a new color.</para>

<para>The dropdown box above the color buttons provides you with several
different blend effects.  Choose one from the list, and it will be
previewed on the small monitor at the top of the window.  Your choices
are:</para>

<variablelist>
<varlistentry>
<term>Flat</term>
<listitem><para>By choosing this mode, you select one color (using the color
button labeled <guibutton>Color 1</guibutton>), and the entire background is
covered with this one color.</para></listitem>
</varlistentry>
<varlistentry>
<term>Pattern</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons). </para> <para>You then select a pattern by clicking
<guilabel>Setup</guilabel>.  This opens a new dialog window, which gives you
the opportunity to select a pattern.  Simply click once on the pattern of your
choice, then click on <guilabel>OK</guilabel>, and &kde; will render the pattern
you selected using the two colors you selected.  For more on patterns, see the
section <ulink url="help:/kcontrol/background/index.html#bkgnd-patterns">Background: Adding, Removing and Modifying
Patterns</ulink>.</para></listitem>
</varlistentry>
<varlistentry>
<term>Background Program</term>
<listitem><para>By selecting this option, you can have &kde; use an external
program to determine the background.  This can be any program of your choosing.
For more information on this option, see the section entitled <ulink
url="help:/kcontrol/background/index.html#bkgnd-programs">Background: Using an external program</ulink>.</para></listitem>
</varlistentry>
<varlistentry>
<term>Horizontal Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons).  &kde; will then start with the color selected by <guilabel>Color
1</guilabel> on the left edge of the screen, and slowly transform into the
color selected by <guilabel>Color 2</guilabel> by the time it gets to the
right edge of the screen.</para></listitem>
</varlistentry>
<varlistentry>
<term>Vertical Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons).  &kde; will then start with the color selected by <guilabel>Color
1</guilabel> on the top edge of the screen, and slowly transform into the color
selected by <guilabel>Color 2</guilabel> as it moves to the bottom of the
screen.</para></listitem>
</varlistentry>
<varlistentry>
<term>Pyramid Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons).  &kde; will then start with the color selected by <guilabel>Color
1</guilabel> in each corner of the screen, and slowly transform into the color
selected by <guilabel>Color 2</guilabel> as it moves to the center of the
screen.</para></listitem> 
</varlistentry>
<varlistentry>
<term>Pipecross Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons).  &kde; will then start with the color selected by <guilabel>Color
1</guilabel> in each corner of the screen, and slowly transform into the color
selected by <guilabel>Color 2</guilabel> as it moves to the center of the
screen. The <quote>shape</quote> of this gradient is  different then the pyramid
gradient.</para></listitem>
</varlistentry>
<varlistentry>
<term>Elliptic Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons).  &kde; will then start with the color selected by <guilabel>Color
2</guilabel> in the center of the screen, and slowly transform into the color
selected by <guilabel>Color 1</guilabel> as it moves to the edges, in an
elliptical pattern.</para></listitem> 
</varlistentry>
</variablelist>

<para>The setup button is only needed for if you select <guilabel>Background
program</guilabel> or <guilabel>Patterns</guilabel>.  In these instances,
another window will appear to configure the specifics.</para>
<para><emphasis>Wallpaper</emphasis></para>
<para>To select a new background image first, click on the
<guilabel>Wallpapers</guilabel> tab, then  you can either select an image from the

drop-down list labeled <guilabel>Wallpaper</guilabel> or select
<guibutton>Browse...</guibutton> and select an image file from a file
selector.</para>

<para>The image can be displayed in six different ways:</para>
<variablelist>
<varlistentry>
<term>No wallpaper</term> 
<listitem><para>No image is displayed.  Just the background colors.</para>
</listitem></varlistentry>
<varlistentry>
<term>Centered</term> 
<listitem><para>The image will be centered on the screen.  The background colors
will be present anywhere the image does not cover.</para> </listitem>
</varlistentry>
<varlistentry>
<term>Tiled</term>
<listitem><para>The image will be duplicated until it fills the entire
desktop. The first image will be placed in the upper left corner of the screen,
and duplicated downward and to the right.</para> </listitem>
</varlistentry>
<varlistentry>
<term>Center Tiled</term>
<listitem><para>The image will be duplicated until it fills the entire
desktop. The first image will be placed in the center of the screen, and
duplicated upward, downward to the right, and to the left.</para> </listitem>
</varlistentry>
<varlistentry>
<term>Centered Maxpect</term>
<listitem><para>The image will be placed in the center of the screen.  It will
be scaled to fit the desktop, but it will not change the aspect ratio of the
original image.  This will provide you with an image that is not distorted.
</para> </listitem>
</varlistentry>
<varlistentry>
<term>Scaled</term>
<listitem><para>The image will be scaled to fit the desktop.  It will be
stretched to fit all four corners.</para> </listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="kdmconfig-shutdown">
<title><guilabel>Shutdown</guilabel></title>

<para><guilabel>Allow Shutdown</guilabel></para>
<para>Use these dropdown box to choose who is allowed to shut down:</para>
<itemizedlist>
<listitem>
<para><guilabel>Nobody</guilabel>: No one can shutdown the computer using
&kdm;.  You must be logged in, and execute a command.</para>
</listitem>
<listitem>
<para><guilabel>Everybody</guilabel>:  Everyone can shutdown the computer using
&kdm;.</para>
</listitem>
<listitem><para><guilabel>Only Root</guilabel>: &kdm; requires that the
<systemitem>root</systemitem> password be entered before shutting down the
computer.</para></listitem> 
</itemizedlist>

<para>You can independently configure who is allowed to issue a
shutdown command for the <guilabel>Local:</guilabel> and
<guilabel>Remote:</guilabel> users.</para>

<para><emphasis>Commands</emphasis></para> <para>Use these text fields to
define the exact shutdown command.</para> <para>The
<guilabel>Halt:</guilabel> command defaults to <!-- Are these defaults still
correct? they disagree with what's in --> <!-- kdmrc -->
<command>/sbin/halt</command>.  The restart command defaults to
<command>/sbin/reboot</command>.</para>

<para>When <guilabel>Show boot options</guilabel> is enabled, &kdm;
will on reboot offer you options for the lilo boot manager. For this
feature to work, you will need to supply the correct paths to your
<command>lilo</command> command and to lilo's map file.</para>


<sect3 id="kdmconfig-sess">
<title>Session types</title>

<para>Define which session types should be accessible from the login
window.</para>

<para> For more information on this subject, look at <filename
class="directory">/etc/X11/xdm/Xsession</filename> to find your
<application>xdm</application> setup files.  Also review the <ulink
url="man:xdm">xdm man pages</ulink>, especially under the SESSION
PROGRAM section.</para>

<para>To add a session, type its name in the
blank entitled <guilabel>New types</guilabel>, and click
<guibutton>Add new</guibutton>. </para>

<para>To remove a session, select the session from the list and click
<guibutton>Remove</guibutton>.</para>

</sect3>
</sect2>
<sect2 id="kdmconfig-users">
<title>Users</title>

<para>From here you can change the way users are represented in the
login window.</para>

<para>You may disable the user list in &kdm; entirely in the
<guilabel>Show Users</guilabel> section.  You can choose from:</para>
<variablelist>
<varlistentry>
<term><guilabel>None</guilabel></term>
<listitem>
<para>Do not show any users.  This is the most secure setting, since an
attacker would then have to guess a valid login name as well as a
password. It's also the preferred option if you have more than a
handful of users to list, or the list itself would become
unwieldy.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Selected only</guilabel></term>
<listitem>
<para>Only show users you have specifically enabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Not hidden</guilabel></term>
<listitem>
<para>Allows you to select a list of users that should
<emphasis>not</emphasis> be shown, and all other users will be
listed.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Independently of the users you specify by name, you can use the
<guilabel>System UIDs</guilabel> to specify a range of valid
<acronym>UID</acronym>s that are shown in the list.  By default user
id's under 1000, which are often system or daemon users, and user id's
over 65000, are not shown.</para>

<para>You can also enable the <guilabel>Sort users</guilabel>
checkbox, to have the user list sorted alphabetically.  If this is
disabled, users will appear in the order they are listed in the
password file.</para>

<para>If you choose to show users, then the login window will show
images (which you select), of a list of users.  When someone is ready
to login, they may select their user name/image, enter their password,
and they are granted access.  </para>

<para>If you permit a user image, then you can configure the source
for those images.</para>

<para>The available options for the <guilabel>User Image
Source</guilabel> are:</para>
<!-- user image sources list here -->

<para>You can configure the admin picture here, for each user on the
system.  Depending on the order selected above, users may be able to
override your selection.</para>

<para>If you choose not to show users, then the login window will be
more traditional.  Users will need to type their username and password
to gain entrance.  This is the preferred way if you have many users on
this terminal.</para>

<sect3 id="kdmconfig-showusers">
<title>To show (and sort) or not to show users</title>

<para>Along the right edge of the window are two check boxes:</para>

<para>If <guilabel>Show users</guilabel> is selected you have chosen to
show images of users, instead of making them type their login
name.</para>

<para>If <guilabel>Sort users</guilabel> is selected, then the list of
users will be sorted alphabetically in the login window.  If unchecked,
users will be listed in the same order as they are on this page.  If
<guilabel>Show users</guilabel> is not checked, this has no
effect.</para>

</sect3>

<sect3 id="kdmconfig-whichusers">
<title>How to determine which users to show and which users to hide</title>

<para>Below the user image box, and above the <guilabel>Show
users</guilabel> check box, is a set of two radio buttions:</para>

<itemizedlist>
<listitem><para>Show only selected users: If this option is selected, only the
users contained in the list labelled <guilabel>Selected Users</guilabel>, will
be displayed in the login window. If <guilabel>Show users</guilabel> is not
checked, this has no effect.</para></listitem>
<listitem><para>Show all users but no-show users: If this option is selected,
all users will be listed, <emphasis>except</emphasis> those users contained in
the list entitled <guilabel>No show users</guilabel>.  If <guilabel>Show
users</guilabel> is not checked, this has no effect.  </para></listitem>
</itemizedlist>

</sect3>

<sect3 id="kdmconfig-select">
<title>Select users</title>

<para>This page contains three listboxes. The large listbox on the left
shows all the users on the system which might be a genuine user.</para>

<para>The top rightmost listbox shows the selected users and the bottom
rightmost listbox shows the users we do not want displayed in the login
window.</para>

<para>To move a user from one listbox to another you click on the
username in the listbox and click <guibutton>&gt;&gt;</guibutton> to
move the user from the leftmost box the the rightmost box or
<guibutton>&lt;&lt;</guibutton> to move the user from the rightmost box
to the leftmost box.</para>

</sect3>

<sect3 id="kdmconfig-image">
<title>Images</title>

<note><para>This section of the manual only applies if <guilabel>Show
users</guilabel> is selected.  If it is not, this image box has no
effect.</para></note>

<para>Every user on the system can be represented by an image. The image
for each user is kept in a file called
<filename>$<envar>KDEDIR</envar>/share/apps/kdm/pics/users/$<envar>USER</envar>.xpm</filename>.
If there is no such file for a particular user, the file
<filename>$<envar>KDEDIR</envar>/share/apps/kdm/pics/users/default.xpm</filename>
will be used instead.</para>

<para>To assign a new image to a user just select the user in one of the
listboxes and either drop an imagefile on the image button to the right
or click on the image button and select a new image from the image
selector.</para>

<para>If no user is currently selected you will be asked if you want to change
the default image.</para>

<para>The replacement is performed by a &konqueror; process so if the
imagefile already exists you will be prompted by &konqueror; if you
want to replace it. If you confirm the image will be replaced - you will
<emphasis>NOT</emphasis> have to press the <guibutton>Apply</guibutton>
button.</para>

</sect3>
</sect2>

<sect2 id="kdmconfig-convenience">
<title>Convenience</title>

<para>In the <guilabel>convenience</guilabel> tab you can configure
some options that make life easier for lazy people, like automatic
login or disabling passwords.</para>

<important><para>Please think more than twice before using these
options. Every option in the <guilabel>Convenience</guilabel> tab is
well-suited to seriously compromise your system security. Practically,
these options are only to be used in a completely non-critical
environment, &eg; a private computer at home.  </para></important>

<sect3 id="loginmanager-convenience-autologin">
<title>Automatic Login</title>

<para>Automatic login will give anyone access to a certain account on
your system without doing any authentication.  You can enable it using
the option <guilabel>Enable auto-login</guilabel>.</para>

<para>You can choose the account to be used for automatic login from
the list labelled <guilabel>User:</guilabel>.</para>

</sect3>

<sect3 id="loginmanager-convenience-nopasswd">
<title><guilabel>Password-Less Login</guilabel></title>

<para>Using this feature, you can allow certain users to login without
having to provide their password. Enable this feature using the
<guilabel>Enable password-less logins</guilabel> option.</para>

<para>Below this option you'll see a list of users on the system.
Enable password-less login for specific users by checking the checkbox
next to the login names.  By default, this feature is disabled for
all users.</para>

<important><para>Again, this option should only be used in a safe
environment. If you enable it on a rather public system you should
take care that only users with heavy access restrictions are granted
password-less login, &eg;
<systemitem>guest</systemitem>.</para></important>

<para>The <guilabel>Automatically login after X server crash</guilabel>
option allows you to skip the authentication procedure when your X
server accidentally crashed.</para>

<para>You can also choose which user is <quote>preselected</quote>
when &kdm; starts. The default is <guilabel>None</guilabel>, but you
can choose <guilabel>Previous</guilabel> to have &kdm; default to the
last successfully logged in user, or you can
<guilabel>Specify</guilabel> a particular user to always be selected
from the list.  You can also have &kdm; set the focus to the password
field, so that when you reach the &kdm; login screen, you can type the
password immediately.</para>

</sect3>

</sect2>

</sect1>

</chapter>

&kdmrc-ref;

<!-- ************************************************************ -->   
<chapter id="configuring-your-system-for-kdm">
<title>Configuring your system to use &kdm;</title>

<para>This chapter assumes that your system is already configured to
run the X Window System, and that you only need to reconfigure it to
allow graphical login.</para>

<sect1 id="setting-up-kdm">
<title>Setting up &kdm;</title>

<para>The fundamental thing that controls whether your computer boots
to a terminal prompt (console mode) or a graphical login prompt is the
default runlevel.  The runlevel is set by the program <application>
<ulink url="man:init">/sbin/init</ulink></application> under the
control of the configuration file
<filename>/etc/inittab</filename>. The default runlevels used by
different &UNIX; systems (and different &Linux; distributions) vary,
but if you look at <filename>/etc/inittab</filename> the start of it
should be something like this:</para>

<screen># Default runlevel. The runlevels used by RHS are:
# 0 - halt (Do NOT set initdefault to this)
# 1 - Single user mode
# 2 - Multiuser, without NFS
# 3 - Full multiuser mode
# 4 - unused
# 5 - X11
# 6 - reboot (Do NOT set initdefault to this)

id:3:initdefault:  
</screen>

<para>All but the last line of this extract are comments. The comments
show that runlevel 5 is used for X11 and that runlevel 3 is used for
multi-user mode without X11 (console mode). The final line specifies
that the default runlevel of the system is 3 (console mode). If your
system currently uses graphical login (for example, using &xdm;) its
default runlevel will match the runlevel specified for X11.</para>

<para>The runlevel with graphical login (&xdm;) for some common &Linux;
distributions are:</para>

<itemizedlist>
<listitem><para>5 for &RedHat; 3.x and later, and for &Mandrake;</para></listitem>
<listitem><para>4 for Slackware</para></listitem>
<listitem><para>3 for &SuSE;. 4.x and 5.x</para></listitem>
</itemizedlist>

<para>The first step in configuring your system is to ensure that you
can start &kdm; from the command line. Once this is working, you can
change your system configuration so that &kdm; starts automatically
each time you reboot your system.</para>

<para>To test &kdm;, you must first bring your system to a runlevel
that does not run &xdm;. To do so, issue a command like this:</para>

<screen><command>/sbin/init <option>3</option></command></screen>

<para>Instead of the number <option>3</option> you should specify the
appropriate runlevel for console mode on your system.</para>

<para>If your system uses Pluggable Authentication Modules
(<abbrev>PAM</abbrev>), which is normal with recent &Linux; and Solaris
systems, you should check that your <abbrev>PAM</abbrev> configuration permits
login through the service named <literal>kde</literal>. If you previously used
&xdm; successfully, you should not need to make any
changes to your <abbrev>PAM</abbrev> configuration in order to use
&kdm;. <filename>/etc/pam.conf</filename> or
<filename>/etc/pam.d/kde</filename>. Information on configuring
<abbrev>PAM</abbrev> is beyond the scope of this handbook, but
<abbrev>PAM</abbrev> comes with comprehensive documentation (try looking in
<filename>/usr/share/doc/*pam*/html/</filename>).</para>

<para>Now it's time for you to test &kdm; by issuing the following
command:</para>

<screen><command>kdm <option>-nodaemon</option></command>
</screen>

<para>If you get a &kdm; login dialog and you are able to log in,
things are going well.  The main thing that can go wrong here is that
the run-time linker might not find the shared &Qt; or &kde; libraries.
If you have a binary distribution of the &kde; libraries, make sure
&kdm; is installed where the libraries believe &kde; is installed and
try setting some environment variables to point to your &kde; and &Qt;
libraries.</para>

<para>For example:</para>

<screen><command>export 
<option>KDEDIR=<replaceable>/opt/kde</replaceable></option></command>
<command>export 
<option>QTDIR=<replaceable>/usr/lib/qt2</replaceable></option></command>
<command>export 
<option>PATH=<replaceable>$KDEDIR/bin:$QTDIR/bin:$PATH</replaceable></option></command>
<command>export 
<option>LD_LIBRARY_PATH=<replaceable>$KDEDIR/lib:$QTDIR/lib</replaceable></option></command>
</screen>

<para>If you are still unsuccessful, try starting &xdm; instead, to
make sure that you are not suffering from a more serious X
configuration problem.</para>

<para>When you are able to start &kdm; successfully, you can start to
replace &xdm; by &kdm;. Again, this is distribution-dependent.</para>

<itemizedlist>
<listitem>
<para>For &RedHat;, edit <filename>/etc/inittab</filename>, look for the
string xdm and replace it with &kdm; (including all paths).</para>
</listitem>
<listitem>
<para>For &Mandrake;, the X11 runlevel in
<filename>/etc/inittab</filename> invokes the shell script
<filename>/etc/X11/prefdm</filename>, which is set up to select from
amongst several display managers, including &kdm;. Make sure that all
the paths are correct for your installation.</para> 
</listitem>
<listitem>
<para>For &SuSE;, edit <filename>/sbin/init.d/xdm</filename> to add a
first line:</para>

<screen>. /etc/rc.config
DISPLAYMANAGER=kdm
export DISPLAYMANAGER</screen>
</listitem>
<listitem><para>For FreeBSD, edit <filename>/etc/ttys</filename> and find
the line like this:
<screen>ttyv8   "/usr/X11R6/bin/xdm -nodaemon"  xterm   off secure</screen>
and edit it to this:
<screen>ttyv8   "/usr/local/bin/kdm -nodaemon"  xterm   on secure</screen>
</para>
</listitem>

<listitem><para>Most other distributions are a variation of one of
these.</para></listitem>
</itemizedlist>

<para>At this stage, you can test &kdm; again by bringing your system
to the runlevel that should now run &kdm;. To do so, issue a command
like this:</para>

<screen><command>/sbin/init <option>5</option></command>
</screen>

<para>Instead of the number <option>5</option> you should specify the
appropriate runlevel for running X11 on your system.</para>

<para>The final step is to edit the <parameter>initdefault</parameter>
entry in <filename>/etc/inittab</filename> to specify the appropriate
runlevel for X11.</para>

<warning><para>Before you make this change, ensure that you have a way
to reboot your system if a problem occurs. This might be a
<quote>rescue</quote> floppy-disk provided by your operating system
distribution or a specially-designed <quote>rescue</quote>
floppy-disk, such as <literal>tomsrtbt</literal>. Ignore this advice
at your peril.</para></warning>

<para>When you reboot your system, you should end up with the
graphical &kdm; login dialog.</para>

<para>If this step is unsuccessful the most likely problem is that the
environment used at boot time differs from the environment that you
used for testing at the command line.
If you are trying to get two versions of KDE to co-exist,
be particularly careful that the settings you use for your
<envar>PATH</envar> and <envar>LD_LIBRARY_PATH</envar> environment
variables are consistent, and that the startup scripts are not
over-riding them in some way.</para>

</sect1>

</chapter>

<chapter id="different-window-managers-with-kdm">
<title>Supporting multiple window managers</title>

<para>The main dialog box for &kdm; includes a <guilabel>Session
Type:</guilabel> drop-down box, which allows you to select a window
manager to use for your session. This chapter describes the changes
that you must make to your configuration files in order to support
this feature.</para>

<para>The options that appear in the <guilabel>Session
Type:</guilabel> drop-down box are <ulink url="KDM">configured</ulink>
by entries in the <literal>KDM</literal> section of &kdmrc;.</para>

<para>When you log in using &kdm;, the shell script
<filename>Xsession</filename> is executed.  The session type that you select is
passed as a command-line argument.  (<filename>Xsession</filename> can be found
in <filename>/etc/X11/xdm/</filename> for Redhat and Mandrake, and in
<filename>/usr/X11R6/lib/X11/xdm/</filename> for S.u.S.E.). Whilst debugging,
you might find it helpful to add this line to
<filename>Xsession</filename>:</para>
      
<screen>echo "$0 || $1 || $2" > $HOME/.Xsession_args </screen>

<para>How you proceed now depends upon how your system usually starts
up window managers. Here are two different approaches, with examples of the
changes that you must make:</para>

<itemizedlist>

<listitem><para>The window manager is started by commands within
<filename>Xsession</filename>. In this case, you can add a case statement to
start the appropriate window manager. Linux Mandrake uses this approach; here is
an extract from <filename>Xsession</filename>:</para>

<screen># now, we see if xdm/gdm/kdm has asked for a specific environment
case $# in
1)
    case $1 in
        kde)
        source /opt/kde2/bin/kde1
        exec startkde
        ;;
        kde2)
        source /opt/kde2/bin/kde2
        exec startkde
        ;;
    	failsafe)
	exec xterm -geometry 80x24-0-0
	;;
	default)
	;;
	*)
	exec /bin/sh -c "$(/usr/sbin/chksession -x=$1)"
	;;
     esac
esac
</screen>
</listitem>

<listitem><para>The window manager is started by another script that
is invoked by <filename>Xsession</filename>. In this case you must
ensure that the parameter passed to <filename>Xsession</filename> is
passed on to that other script. For example, if the window manager is
started like this:</para>

<screen><command>exec <option>$startup</option></command></screen>

<para>you would need to change it to:</para>

<screen><command>exec <option>$startup</option><option>$@</option></command></screen>

<para>Having made this change, you must trace your way through the
startup to find the place where the window manager is started. One
approach uses <filename>xinitrc</filename> to start the window
manager; this allows a system-wide file
<filename>/etc/X11/xinit/xinitrc</filename> or a user-specific file
<filename>$HOME/.xinitrc</filename> to be used. If you edit
<filename>$HOME/.xinitrc</filename>, you may want to save a copy in
<filename>/etc/skel</filename>, so that it will be automatically
generated in every user account you create from now on.  Here is an
example <filename>xinitrc</filename> for a system using this
approach:</para>

<screen>#!/bin/bash
#
# .xsession/.xinitrc
#
# choose a window manager
#

defaultwm=kde
#set the window manager to $1 if it was supplied
windowmgr=${1:-$defaultwm}

#start the respective window managers
case ${windowmgr} in
  kde|kwm|kdestart)
	WINDOWMANAGER=startkde
	;;
  fvwm|fvwm2)
	WINDOWMANAGER=fvwm2
	;;

  fvwm95)
	WINDOWMANAGER=fvwm95
	;;

  *)    WINDOWMANAGER=windowmgr   # default for unknown wm's

esac

#
# load resources
#

if [ -f /usr/X11R6/lib/X11/Xmodmap ]; then
    xmodmap /usr/X11R6/lib/X11/Xmodmap
fi

if [ -f ~/.Xmodmap ]; then
    xmodmap ~/.Xmodmap
fi

if [ -f ~/.Xdefaults ]; then
    xrdb -merge ~/.Xdefaults
fi

if [ -f ~/.Xresources ]; then
    xrdb -merge ~/.Xresources
fi
# 
# finally start the window manager
#
exec $WINDOWMANAGER
</screen>

</listitem>
</itemizedlist>


</chapter>

<chapter id="xdmcp-with-kdm">
<title>Using &kdm; for Remote Logins (&XDMCP;)</title>

<para>&XDMCP; is the Open Group standard, the <quote>X Display Manager
Control Protocol</quote>.  This is used to set up connections between
remote systems over the network.</para>

<para>&XDMCP; is useful in multiuser situations where there are users
with workstations and a more powerful server that can provide the
resources to run multiple X sessions.  For example, &XDMCP; is a good
way to reuse old computers - a Pentium or even 486 computer with 16 Mb
RAM is sufficient to run X itself, and using XDMCP such a computer can
run a full modern &kde; session from a server.  For the server part,
once a single &kde; (or other environment) session is running, running
another one requires very few extra resources.</para>

<para>However, allowing another method of login to your machine
obviously has security implications.  You should run this service only
if you need to allow remote X Servers to start login sessions on your
system. Users with a single &UNIX; computer should not need to run
this.</para>

<!-- Write more stuff -->
</chapter>

<!-- *********************************************************************** -->
<chapter id="Other-Information">
<title>Other sources of information</title>

<para>Since &kdm; is descended from &xdm;, the <ulink
url="man:xdm">xdm man page</ulink> may provide useful background
information. For X-related problems try the man pages <ulink
url="man:X">X</ulink> and <ulink url="man:startx">startx</ulink>. If you have
questions about &kdm; that are not answered by this handbook, take advantage of
the fact the &kdm; is provided under the terms of the <abbrev>GNU</abbrev>
General Public License: look at the source code.
</para>

</chapter>

<!-- *********************************************************************** -->
<chapter id="credits"><title>Credits and License</title>

<para>&kdm; is derived from, and includes code from,
&xdm; (C) Keith Packard, MIT X Consortium.</para>

<para>&kdm; 0.1 was written by Matthias Ettrich. 
Later versions till &kde; 2.0.x were written by Steffen Hansen.
Some new features for &kde; 2.1.x and a major rewrite for &kde; 2.2.x made by
Oswald Buddenhagen.</para>

<para>Other parts of the &kdm; code are copyright by the authors, and
licensed under the terms of the <ulink url="common/gpl-license.html">GNU
GPL</ulink>. Anyone is allowed to change &kdm; and redistribute the result as
long as the names of the authors are mentioned.</para>

<para>&kdm; requires the Qt library, which is copyright Troll Tech AS.</para>

<para>Documentation contributors:
<itemizedlist>

<listitem><para>Documentation written by Steffen Hansen <email>stefh@dit.ou.dk</email></para></listitem>

<listitem><para>Documentation extended by Gregor Zumstein<email>zumstein@ssd.ethz.ch</email>. Last
update August 9, 1998</para></listitem>

<listitem><para>Documentation revised for KDE 2 by Neal Crook<email>nac@forth.org</email>. Last
update August 6, 2000</para></listitem>

<listitem><para>Documentation extended and revised for KDE 2.2 by Oswald Buddenhagen<email>ossi@kde.org</email>. 
Last update August, 2001</para></listitem>

</itemizedlist></para>

<para>Documentation copyright Steffen Hansen, Gregor Zumstein, Neal Crook and
Oswald Buddenhagen. This document also includes large parts of the 
&xdm; man page, which is (C) Keith Packard.</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>

<appendix id="building-and-installing-kdm">
<title>Building and Installing kdm</title>

<para>&kdm; is part of the KDE project. The various component parts of the KDE
project are broken into sections, called packages. &kdm; is part of the package
called kdebase. You can get KDE source code from various Linux and BSD
distribution CDs, or by download from <ulink
url="http://www.kde.org">www.kde.org</ulink> or its mirrors. If you have an
out-of-date source code tree, you can use one of the KDE cvsup servers to bring
it up-to-date whilst using minimal network bandwidth.
</para>

<para>Before building kdebase, you must have built and installed (in
this order) version 2 of the qt library and the KDE packages
kdesupport (optionally) and kdelibs.</para>

<para>In order to build any of the above, you must already have the X Window
System installed, together with a C++ compiler.
If are you building from CVS you will also need
 the GNU configuration tools
<application>automake</application> and
<application>autoconf</application>.</para>

<para>If the last few paragraphs seemed like a foreign language, then
either you have strayed into an Inappropriate Area of this handbook,
or you are about to undergo a Great Learning Experience.</para>

<para>If you managed to satisfy all of the prerequisites, you are unlikely to
have any problems with building and installing kdebase. &kdm; is installed in
your <filename>$KDEDIR/bin</filename> folder.</para>

<note><para><command>make <option>install</option></command> will <emphasis>not</emphasis> overwrite your
previous &kdm; config files including &kdmrc;.</para></note>

</appendix>

<glossary id="glossary">
<title>Glossary</title>

<glossentry id="gloss-greeter">
<glossterm>greeter</glossterm>
<glossdef><para>The greeter is the login dialog, &ie; the part of &kdm;
which the user sees.</para>
</glossdef>
</glossentry>

<glossentry>
<glossterm id="gloss-entropy">entropy</glossterm>
<glossdef><para>...</para></glossdef>
</glossentry>

</glossary>

</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->

