$Id: README,v 2.16 2002/10/12 17:08:24 ossi Exp $

This is the KDE Display Manager (kdm) v0.94 for KDE 3.1, 
the KDE replacement for the X Display Manager (xdm).


How to setup kdm
----------------

KDM's config files are all located in ${kde_confdir}/kdm.
"make install" will create a probably working configuration, either by
deriving it from an already present KDM/XDM installation or by using
defaults if no previous installation is found.

You can change the configuration from the KDE Control Center. 
You will find the Login Manager module in "System" -> "Login Manager".

Have a look at README.pam in the kdebase top level directory if your
system uses PAM.


The Xservers file
-----------------

This file tells kdm which/when/how X-Servers ("desktop sessions", 
"login screens") should be started. The file is backwards compatible with 
XDM's Xservers file, but it contains some extensions:
* @tty. The idea for this is stolen from Solaris (TM). You can specifiy here,
  which text console an X-Server is "covering", so KDM knows which virtual
  terminal to switch to when you select "Console login" and it knows which
  console it should monitor for activity to find out when you're done with
  your console work.
  This is not perfectly suited for Linux, as there X-Servers don't actually
  cover consoles (gettys), but hey, it works. :-)
* reserve. A server marked as reserve is not started at KDM's startup time,
  but when the user explicitly requests it. See "Command FiFos" below.

Example:

:0 local@tty1 /usr/bin/X11/X vt7
:1 local reserve /usr/bin/X11/X :1 vt8


Running KDM from init
---------------------

NOTE, that this description applies to RedHat and must be adapted for
other distributions/systems.

   Edit (as root) /etc/inittab.

   Look for the line: 

       x:5:respawn:/usr/X11/bin/xdm -nodaemon

   Replace it with:

       x:5:respawn:/opt/kde/bin/kdm -nodaemon

   This tells init(8) to respawn KDM, the KDE display manager, when
   the system is in run level 5. 

   To start KDM, either run (as root) /sbin/telinit 5 (to switch to
   run level 5), or (this is risky! don't do it until you _know_ you
   want the system to boot into this every time!) edit /etc/inittab
   and change the line:

       id:3:initdefault:

   to

       id:5:initdefault:

   If you do the latter step, then every time your system boots 
   successfully it will go into run level 5 and run KDM, 
   presenting you the exceedingly cute KDE login screen. 


The command FiFos
-----------------

This is a feature you can use to remote-control KDM. It's mostly intended
for use by ksmserver and kdesktop from a running session, but other 
applications are possible as well.
There are two types of FiFos: the global one (xdmctl) and the per-display 
ones (xdmctl-<display>).
The global one is owned by root, the per-display ones are owned by the user 
currently owning the session (root or the logged in user). Group ownership 
of the FiFos can be set via FifoGroup=, otherwise it's root. The file 
permissions of the FiFos are rw--w---- (0620). The FiFos are created in the 
directory specified by FifoDir=.
The fields of a command are separated by tabs (\t), the fields of a list
are separated by spaces. The command is terminated by a newline (\n).

Global FiFo commands:

"shutdown" ("reboot"|"halt") ("forcenow"|"trynow"|"schedule")
 - same functionality as the shutdown dialog

"login" display ("now"|"schedule") user password session_arguments
 - login user at specified display. if "now" is specified, a possibly
   running session is killed, otherwise the login is done after the session
   exits.

Per-display Fifo commands:

"shutdown" ("reboot"|"halt") ["forcenow"|"trynow"|"schedule"]
 - Same functionality as the shutdown dialog. It takes effect when the
   session at this display exits.

"lock"
 - The display is marked as locked. If the X-Server crashes in this state,
   no auto-relogin will be performed even if the option is on.

"unlock"
 - Reverse the effect of "lock": re-enable auto-relogin.

"reserve" [timeout in seconds]
 - Start a reserve login screen. If nobody logs in within the specified amount
   of time (one minute by default), the display is removed again. When the
   session on the display exits, the display is removed, too.

"suicide"
 - The currently running session is forcibly terminated. No auto-relogin is
   attempted, but a scheduled "login" command will be executed.


Random rambings and license information
---------------------------------------

Version 0.1 of kdm is copyright
	Matthias Ettrich <ettrich@trolltech.com>
All later versions copyright:
	(C) 1997-2000 Steffen Hansen <hansen@kde.org>
Since version 0.90 (KDE 2.1) copyright:
	(C) 2000-2002 Oswald Buddenhagen <ossi@kde.org>

The files in the backend directory are licensed under the X licence 
(see www.xfree86.org for more info). 
The files in the chooser and kfrontend directories are licensed under 
the GNU GPL.

Thanks to (in no particular order):
Michael Bach Jensen and Torsten Rahn for drawing icons.
Duncan Haldane for investigation of PAM issues.
Stephan Kulow for helping me with the autoconf stuff.
Martin Baehr for intensive testing and writing the sample Xsession scripts.
Harald Hoyer <Harald.Hoyer@redhat.de> for the chooser
... and _many_ others ...


"It doesn't work!!"
-------------------

More input! ;-)

KDM accepts two command line options related to logging. These options
_must_ come first on the command line, if they are used:

  -debug <n>
    <n> is a decimal or hexadecimal (prefix 0x) number.
    The number is a bitfield, i.e., it is formed by summing up the 
    required values from this table:
    1 (0x1) - core debugging. probably the most useful one.
    2 (0x2) - config reader debugging.
    4 (0x4) - greeter debugging.
    8 (0x8) - ipc debugging. this logs _all_ communication between the
	      core, the config reader and the greeter - including the
	      passwords you type - so edit the log before showing it to
	      somebody.
    16 (0x10) - wait after forking session sub-daemon.
    32 (0x20) - wait after starting config reader.
    64 (0x40) - wait after starting greeter.
	the wait options are only useful, if you need to attach a debugger
	to a process but it crashes before you are able to do so without
	the delay.
    256 (0x100) - core Xauth debugging.
    512 (0x200) - don't fork session sub-daemon, but manage one session
	in the master daemon. not for real-world use.

  -logfile <file>
    <file> is the file to log various messages to.
    For internal reasons there is no option in kdmrc to permanently specify 
    another log file location. If you redirect KDM's standard error output
    to a file, KDM will log there.
    If KDM is configured to use syslog, all internally generated messages 
    are logged to the "daemon" facility. The log usually can be found in 
    /var/log/debug.log and /var/log/daemon.log; make sure, that daemon.* 
    is logged (look at /etc/syslog.conf). 

Send me the logs together with a detailed description what you did and
what happened. If your problem is related to a specific configuration,
you should also attach a tar.gz archive of your kdm config directory.


-- 
Have fun with it (and feel free to comment),

	Oswald Buddenhagen <ossi@kde.org>
