workspace/kdm/README

   1 This is the KDE Display Manager (KDM), a replacement for the
   2 X Display Manager (XDM).
   3
   4 Enter help:kdm into Konqueror's location bar to view the manual.
   5
   6 Semi-official home page: http://developer.kde.org/~ossi/sw/kdm.html
   7
   8
   9 cmake options that affect KDM
  10 -----------------------------
  11
  12 -DKDE4_COMMON_PAM_SERVICE:STRING=service
  13 -DKDE4_KDM_PAM_SERVICE:STRING=service
  14   Set the PAM service used by all of kdebase resp. specifically by KDM.
  15   Whether PAM should be used in the first place is auto-detected.
  16
  17 -DKDE4_KERBEROS4:BOOL=ON
  18   Compile KDM (and the LDAP KIO slave) with KTH Kerberos 4 support. Note
  19   that this does not work with the Kerberos 4 compatibility layer found in
  20   MIT Kerberos 5. This affects KDM only if PAM is not used.
  21
  22 -DKDE4_AFS:BOOL=ON
  23   Compile KDM with AFS support. Depends on KDE4_KERBEROS4.
  24
  25 -DKDE4_KRB5AUTH:BOOL=ON
  26 -DKDE4_RPCAUTH:BOOL=ON
  27   Compile KDM with Kerberos 5 resp. secure RPC support for X authorization
  28   cookies. It's pretty pointless to enable this if you don't use an X server
  29   that supports it.
  30
  31   If you want user authentication against a Kerberos realm, compile KDM with
  32   PAM support and use the appropriate module.
  33
  34 -DKDE4_XDMCP:BOOL=OFF
  35   Compile KDM without XDMCP support.
  36
  37 -DKDE4_KDM_XCONSOLE:BOOL=ON
  38   Compile KDM with a builtin "xconsole" replacement in the greeter. I don't
  39   consider this too useful, but SuSE wanted it, so it's there. ;)
  40
  41
  42 KDM's file system layout
  43 ------------------------
  44
  45 ${kde_confdir} is usually ${prefix}/share/config
  46 ${kde_datadir} is usually ${prefix}/share/apps
  47 The indented locations are envisioned for a configuration shared with GDM.
  48
  49 ${kde_confdir}/kdm/{kdmrc,Xservers,Xaccess,Xwilling,...}
  50 ${kde_datadir}/kdm/sessions/*.desktop
  51   /etc/X11/sessions/,/usr/share/xsessions/
  52 ${kde_datadir}/kdm/pics/users/
  53 ${kde_datadir}/kdm/pics/
  54 ${kde_datadir}/kdm/faces/*.face{,.icon}
  55   /usr/share/faces/
  56 /var/run/xauth/A*
  57 /var/run/xdmctl/xdmctl*
  58 /var/run/kdm.pid
  59 /var/lib/kdm/kdmsts
  60 <site-specific>/*.dmrc
  61 $HOME/.face{,.icon}
  62 $HOME/.dmrc
  63
  64
  65 How to setup KDM
  66 ----------------
  67
  68 KDM's config files are all located in ${kde_confdir}/kdm.
  69 "make install" will create a probably working configuration, either by
  70 deriving it from an already present KDM/XDM installation or by using
  71 defaults if no previous installation is found.
  72
  73 You can change the configuration from the KDE Control Center. You will
  74 find the "Login Manager" module in the "System Administration" group.
  75
  76 Have a look at README.pam in the kdebase top level directory if your
  77 system uses PAM.
  78
  79
  80 Running KDM from init
  81 ---------------------
  82
  83 NOTE, that this description applies to RedHat 5.x and must be adapted for
  84 other distributions/systems. Generally I'd advise _against_ starting KDM
  85 directly from init - better use a proper init script, possibly by slightly
  86 modifying the XDM init script shipped by your distribution.
  87
  88    Edit (as root) /etc/inittab.
  89
  90    Look for the line:
  91
  92        x:5:respawn:/usr/X11/bin/xdm -nodaemon
  93
  94    Replace it with:
  95
  96        x:5:respawn:/opt/kde/bin/kdm
  97
  98    This tells init(8) to respawn KDM, the KDE display manager, when
  99    the system is in run level 5.
 100    Note that KDM does not need the -nodaemon option.
 101
 102    To start KDM, either run (as root) /sbin/telinit 5 (to switch to
 103    run level 5), or (this is risky! don't do it until you _know_ you
 104    want the system to boot into this every time!) edit /etc/inittab
 105    and change the line:
 106
 107        id:3:initdefault:
 108
 109    to
 110
 111        id:5:initdefault:
 112
 113    If you do the latter step, then every time your system boots
 114    successfully it will go into run level 5 and run KDM,
 115    presenting you the exceedingly cute KDE login screen.
 116
 117
 118 "It doesn't work!!"
 119 -------------------
 120
 121 More input! ;-)
 122
 123 KDM accepts two command line options related to logging:
 124
 125   -debug <n>
 126     <n> is a decimal or hexadecimal (prefix 0x) number.
 127     The number is a bitfield, i.e., it is formed by summing up the
 128     required values from this table:
 129     1 (0x1) - core debugging. Probably the most useful one.
 130     2 (0x2) - config reader debugging.
 131     4 (0x4) - greeter debugging.
 132     8 (0x8) - IPC debugging. This logs _all_ communication between the
 133               core, the config reader and the greeter - including the
 134               passwords you type, so edit the log before showing it to
 135               somebody.
 136               This attempts to synchronize the processes to interleave the
 137               log messages optimally, but will probably fail unless you use
 138               -debug 0x80 as well.
 139     16 (0x10) - wait after forking session sub-daemon.
 140     32 (0x20) - wait after starting config reader.
 141     64 (0x40) - wait after starting greeter.
 142         The wait options are only useful if you need to attach a debugger
 143         to a process, but it crashes before you are able to do so without
 144         the delay. See below.
 145     128 (0x80) - don't use syslog for internally generated messages.
 146     256 (0x100) - core Xauth debugging.
 147     1024 (0x400) - run config reader and greeter through valgrind.
 148     2048 (0x800) - run config reader and greeter through strace.
 149
 150     Logs from "-debug 7" are usually a good start.
 151
 152   -logfile <file>
 153     <file> is the file to log various messages to. The default log file is
 154     /var/log/kdm.log. For internal reasons there is no option in kdmrc to
 155     permanently specify the log file location. If you redirect KDM's
 156     standard error output to a file, KDM will log there.
 157     If KDM is configured to use syslog (and it _very_ probably is on any
 158     modern system), all internally generated messages are logged to the
 159     "daemon" facility. The log usually can be found in /var/log/debug.log
 160     and /var/log/daemon.log; make sure that daemon.* is logged (look at
 161     /etc/syslog.conf).
 162     If you have problems logging in and your system uses PAM (also quite
 163     probable on modern systems), the "auth" and "authpriv" syslog facilities
 164     are interesting, too. This is not relevant for Linux-PAM starting with
 165     version 0.99.
 166
 167 Before reproducing the problem for log submission, truncate the old logs -
 168 I'm really not interested in a month's worth of your system's history.
 169 Send me all the logs together with a detailed description of what you did
 170 and what happened. If your problem is related to a specific configuration,
 171 you should also attach a tar.gz archive of your KDM config directory.
 172
 173 If I request a backtrace from you and KDM didn't create one yet via the
 174 usual DrKonqi procedure, you'll need to do that yourself. The keyphrase
 175 is "attaching gdb". How exactly this is done depends on the part that
 176 crashes:
 177 - master daemon. Actually you should never need to attach to it, as
 178   you can start it within the debugger already:
 179   # gdb --args kdm -nodaemon -debug 7
 180   (gdb) run
 181 - display subdaemon. Find (using ps) the process with a name like
 182   "-:0" (where :0 is actually the display this process is for). This
 183   process' PPID is the master daemon. Attach to it this way:
 184   # gdb kdm <the PID you found>
 185   (gdb) cont
 186   If the subdaemon crashes before you can attach, add 16 to the debug flags
 187   when you start KDM.
 188 - config reader. You will need to add 32 to the debug flags almost certainly.
 189   The PPID will be the master daemon as well.
 190   # gdb kdm_config $(pidof kdm_config)
 191   (gdb) cont
 192 - greeter. If it's too fast, add 64 to -debug. The PPID will be the subdaemon.
 193   # gdb kdm_greet $(pidof kdm_greet)
 194   (gdb) cont
 195   The simplification with "pidof" works only if you have only one display,
 196   otherwise you need to find the PID manually (by using ps -fx).
 197 Once you got gdb attached to the offending process, do whatever is needed
 198 to make it crash (probably nothing, if you had to use a delay parameter).
 199 Once it crashed, gdb will tell you a signal name, like SIGSEGV - that's the
 200 first interesting part for me. Then you need to create the actual backtrace:
 201   (gdb) where full
 202 The output of this command is interesting for me. If it fails, use "bt"
 203 instead.
 204 I might request a backtrace even if nothing crashes, but instead hangs. In
 205 this case don't use "cont" after attaching, but use "bt" right away. If the
 206 process is already running, interrupt it with ctrl-c.
 207 For obvious reasons you need to run gdb on a different virtual terminal than
 208 the X server. To get there, press alt-ctrl-f1 and log in as root. To
 209 switch to the X server's VT, press alt-ctrl-f7 (the exact function key may
 210 be different on your system). You may also use a remote login from a
 211 second machine. In any case it is advantageous to have mouse support on the
 212 debugging console for copying the backtrace.
 213 Note that a backtrace is usually _much_ more useful if the binary contains
 214 debugging info, so unless your distribution provides debug symbol packages,
 215 you should install from source with the -DCMAKE_BUILD_TYPE:STRING=debugfull
 216 cmake flag if at all possible.
 217
 218
 219 Random rambings and license information
 220 ---------------------------------------
 221
 222 Version 0.1 of KDM is copyright
 223         Matthias Ettrich <ettrich@trolltech.com>
 224 All later versions copyright:
 225         (C) 1997-2000 Steffen Hansen <hansen@kde.org>
 226 Since version 0.90 (KDE 2.1) copyright:
 227         (C) 2000-2007 Oswald Buddenhagen <ossi@kde.org>
 228
 229 The files in the backend directory are licensed under the X licence
 230 (see http://en.wikipedia.org/wiki/X_Licence#License_terms for more info).
 231 The files in the kfrontend directory are licensed under the GNU GPL.
 232
 233 Thanks to (in no particular order):
 234 Michael Bach Jensen and Torsten Rahn for drawing icons.
 235 Duncan Haldane for investigation of PAM issues.
 236 Stephan Kulow for helping with the autoconf stuff.
 237 Martin Baehr for intensive testing and writing the sample Xsession scripts.
 238 Harald Hoyer <Harald.Hoyer@redhat.de> for the (now obsoleted) chooser.
 239 SuSE for employing me (ossi) for three months to work on kdm.
 240 BasysKom for sponsoring my (ossi's) work on the conversation plugin stuff.
 241 ... and _many_ others ...
 242
 243
 244 --
 245 Have fun with it (and feel free to comment),
 246
 247         Oswald Buddenhagen <ossi@kde.org>