diff options
Diffstat (limited to 'kdm/README')
| -rw-r--r-- | kdm/README | 454 |
1 files changed, 454 insertions, 0 deletions
diff --git a/kdm/README b/kdm/README new file mode 100644 index 000000000..bdf34814e --- /dev/null +++ b/kdm/README @@ -0,0 +1,454 @@ +This is the K Display Manager (KDM) for KDE 3.4, +the KDE replacement for the X Display Manager (XDM). + +Semi-official home page: http://devel-home.kde.org/~ossi/sw/kdm.html + + +configure options that affect KDM +--------------------------------- + +--with-pam[=service] + Compile KDM (and other parts of kdebase) with PAM support. The default + service is "kde". PAM is automatically used if found. + +--with-kdm-pam=service + Override the PAM service used specifically by KDM. Depends on --with-pam. + +--with-shadow + Compile KDM (and other parts of kdebase) with shadow password support. + Shadow passwords are automatically used if found. This affects KDM only + if PAM is not used. + +--with-krb4[=path] + Compile KDM (and the LDAP KIO slave) with KTH Kerberos 4 support. Note + that this does not work with the Kerberos 4 compatibility layer found in + MIT Kerberos 5. This affects KDM only if PAM is not used. + +--with-afs + Compile KDM with AFS support. Depends on --with-krb4. + +--with-krb5auth[=path] +--with-rpcauth + Compile KDM with Kerberos 5 resp. secure RPC support for X authorization + cookies. It's pretty pointless to enable this if you don't use an X server + that supports it. + + If you want user authentication against a Kerberos realm, compile KDM with + PAM support and use the appropriate module. + +--without-xdmcp + Compile KDM without XDMCP support. + +--with-kdm-xconsole + Compile KDM with a builtin "xconsole" replacement in the greeter. I don't + consider this too useful, but SuSE wanted it, so it's there. ;) + + +KDM's file system layout +------------------------ + +${kde_confdir} is usually ${prefix}/share/config +${kde_datadir} is usually ${prefix}/share/apps +The indented locations are envisioned for a configuration shared with GDM. + +${kde_confdir}/kdm/{kdmrc,Xservers,Xaccess,Xwilling,...} +${kde_datadir}/kdm/sessions/*.desktop + /etc/X11/sessions/,/usr/share/xsessions/ +${kde_datadir}/kdm/pics/users/ +${kde_datadir}/kdm/pics/ +${kde_datadir}/kdm/faces/*.face{,.icon} + /usr/share/faces/ +/var/run/xauth/A* +/var/run/xdmctl/xdmctl* +/var/run/kdm.pid +/var/lib/kdm/kdmsts +<site-specific>/*.dmrc +$HOME/.face{,.icon} +$HOME/.dmrc + + +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 the "System Administration" group. + +Have a look at README.pam in the kdebase top level directory if your +system uses PAM. + + +Configuring session types +------------------------- + +The way session types are configured changed drastically in KDE 3.2. +Session types are now represented by .desktop files in appropriate locations. +The format of the .desktop files is (not yet) defined in the FreeDesktop.org +desktop entry spec. Differences to "standard" .desktop files are: +- the Type is fixed to XSession and can be omitted +- the Encoding is fixed to UTF-8 and can be omitted +- the Exec field will be passed to "eval exec" in a bourne shell; no macro + expansion is performed on it. "default", "custom" and "failsafe" are magic + constants that cause special actions. +- Name, Comment, TryExec and Hidden are supported +- the remaining keys have no meaning currently +Session types are internally identified by filename (without extension); +that's what will be saved to ~/.dmrc and what DESKTOP_SESSION will be set to. +For every magic Exec constant a session type of the same name exists. + +Unless your system is configured differently already, you should create a +directory ${kde_confdir}/kdm/sessions and add this to kdmrc: + +[X-*-Core] +SessionsDirs=${kde_confdir}/kdm/sessions,${kde_datadir}/kdm/sessions + +(Note that you must use actual paths instead of variables, see the section +about KDM's file system layout.) +Do any changes only in the config directory - any changes in the data +directory will be lost after the next KDE update. + +To override a session type, copy the .desktop file from the data dir to the +config dir and edit it at will. Removing the shipped session types can be +accomplished by "shadowing" them with .desktop files containing Hidden=true. +For the magic session types no .desktop files exist by default, but KDM +pretends they would, so you can override them like any other type. +I guess you already know how to add a new session type by now. ;-) + + +Running KDM from init +--------------------- + +NOTE, that this description applies to RedHat 5.x and must be adapted for +other distributions/systems. Generally I'd advise _against_ starting KDM +directly from init - better use a proper init script, possibly by slightly +modifying the XDM init script shipped by your distribution. + + 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 + + This tells init(8) to respawn KDM, the KDE display manager, when + the system is in run level 5. + Note that KDM does not need the -nodaemon option. + + 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 sockets +------------------- + +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. + +The sockets are UNIX domain sockets which live in subdirectories of the +directory specified by FifoDir=. The subdir is the key to addressing and +security; the sockets all have the file name "socket" and file permissions +rw-rw-rw- (0666). This is because some systems don't care for the file +permissions of the socket files. +There are two types of sockets: the global one (dmctl) and the per-display +ones (dmctl-<display>). +The global one's subdir is owned by root, the subdirs of the per-display +ones' are owned by the user currently owning the session (root or the +logged in user). Group ownership of the subdirs can be set via FifoGroup=, +otherwise it's root. The file permissions of the subdirs are rwxr-x--- (0750). + +The fields of a command are separated by tabs (\t), the fields of a list +are separated by spaces, literal spaces in list fields are denoted by "\s". +The command is terminated by a newline (\n). +The same applies to replies. The reply on success is "ok", possibly followed +by the requested information. The reply on error is an errno-style word (e.g., +"perm", "noent", etc.) followed by a longer explanation. + +Global commands: + +"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. + session_arguments are printf-like escaped contents for .dmrc. Unlisted + keys will default to previously saved values. + +Per-display commands: + +"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. + +"suicide" + - The currently running session is forcibly terminated. No auto-relogin is + attempted, but a scheduled "login" command will be executed. + +Commands for all sockets: + +"caps" + - Returns a list this socket's capabilities: + "kdm" - identifies kdm, in case some other DM implements this protocol, too. + "list", "activate", "lock", "suicide", "login" - the respective command + is supported. + "bootoptions" - the "listbootoptions" command and the "=" option to + "shutdown" are supported. + "shutdown <list>" - "shutdown" is supported and allowed to the listed users + (comma-separated). "*" means all authenticated users. + "shutdown" - "shutdown" is supported and allowed to everybody. + "nuke <list>" - forced shutdown is allowed to the listed users. + "nuke" - forced shutdown is allowed to everybody. + "reserve <number>" - reserve displays are configured and <number> are + available at this time. + +"list" ["all"|"alllocal"] + - Return a list of running sessions. By default all active sessions are + listed. If "all" is specified, passive sessions are listed as well. If + "alllocal" is specified, passive sessions are listed as well, but all + incoming remote sessions are skipped. + Each session entry is a comma-separated tuple of: + - Display or TTY name + - VT name for local sessions + - Logged in user's name, empty for passive sessions and outgoing remote + sessions (local chooser mode) + - Session type or remote host for outgoing remote sessions, empty for + passive sessions + - A flag field: + - "t" for tty sessions + - "*" for the display belonging to the requesting socket + - "!" for sessions that cannot be killed by the requesting socket + - New flags might be added later + - New fields might be added later + +"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. + - Permitted only on sockets of local displays and the global socket. + +"activate" (vt|display) + - Switch to a particular VT (virtual terminal). The VT may be specified + either directly (e.g., vt3) or by a display using it (e.g., :2). + - Permitted only on sockets of local displays and the global socket. + +"listbootoptions" + - List available boot options. + => "ok" list default current + default and current are indices into the list and are -1 if unset or + undeterminable. + +"shutdown" ("reboot"|"halt") ["="bootchoice] \ + ("ask"|"trynow"|"forcenow"|"schedule"|\ + start ("-1"|end ("force"|"forcemy"|"cancel"))) + - Request a system shutdown, either a reboot or a halt/poweroff. + - An OS choice for the next boot may be specified from the list returned by + "listbootoptions". + - Shutdowns requested from per-display sockets are executed when the current + session on that display exits. Such a request may pop up a dialog asking + for confirmation and/or authentication. + - start is the time for which the shutdown is scheduled. If it starts with + a plus-sign, the current time is added. Zero means immediately. + - end is the latest time at which the shutdown should be performed if active + sessions are still running. If it starts with a plus-sign, the start time + is added. Minus one means wait infinitely. If end is through and active + sessions are still running, KDM can do one of the following: + * "cancel" - give up the shutdown. + * "force" - shut down nonetheless. + * "forcemy" - shut down nonetheless if all active sessions belong to the + requesting user. Only for per-display sockets. + - start and end are specified in seconds since the UNIX epoch. + - "trynow" is a synonym for "0 0 cancel", "forcenow" for "0 0 force" and + "schedule" for "0 -1". + - "ask" attempts an immediate shutdown and interacts with the user if active + sessions are still running. Only for per-display sockets. + +"shutdown" "cancel" ["local"|"global"] + - Cancel a scheduled shutdown. The global socket always cancels the currently + pending shutdown, while per-display sockets default to cancelling their + queued request. + +"shutdown" "status" + - Return a list with information about shutdowns. + The entries are comma-separated tuples of: + - ("global"|"local") - pending vs. queued shutdown. A local entry can be + returned only by a per-display socket. + - ("halt"|"reboot") + - start + - end + - ("ask"|"force"|"forcemy"|"cancel") + - Numeric user ID of the requesting user, -1 for the global socket. + - The next boot OS choice or "-" for none. + - New fields might be added later. + +There are two ways of using the sockets: +- Connecting them directly. FifoDir is exported as $DM_CONTROL; the name + of per-display sockets can be derived from $DISPLAY. +- By using the kdmctl command (e.g., from within a shell script). + Try "kdmctl -h" to find out more. + +Here is an example bash script "reboot into FreeBSD": + +if kdmctl | grep -q shutdown; then + IFS=$'\t' + set -- `kdmctl listbootoptions` + if [ "$1" = ok ]; then + fbsd=$(echo "$2" | tr ' ' '\n' | sed -ne 's,\\s, ,g;/freebsd/I{p;q}') + if [ -n "$fbsd" ]; then + kdmctl shutdown reboot "=$fbsd" ask > /dev/null + else + echo "FreeBSD boot unavailable." + fi + else + echo "Boot options unavailable." + fi +else + echo "Cannot reboot system." +fi + + +"It doesn't work!!" +------------------- + +More input! ;-) + +KDM accepts two command line options related to logging: + + -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. + This attempts to synchronize the processes to interleave the + log messages optimally, but will probably fail unless you use + -debug 0x80 as well. + 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. See below. + 128 (0x80) - don't use syslog for internally generated messages. + 256 (0x100) - core Xauth debugging. + 1024 (0x400) - run config reader and greeter through valgrind. + 2048 (0x800) - run config reader and greeter through strace. + + Logs from "-debug 7" are usually a good start. + + -logfile <file> + <file> is the file to log various messages to. The default log file is + /var/log/kdm.log. For internal reasons there is no option in kdmrc to + permanently specify the 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 (and it _very_ probably is on any + modern system), 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). + If you have problems logging in and your system uses PAM (also quite + probable on modern systems), the "auth" and "authpriv" syslog facilities + are interesting, too. + +Send me all the logs together with a detailed description of 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. + +If I request a backtrace from you and KDM didn't create one yet via the +usual drkonqi procedure, you'll have to do that yourself. The keyphrase +is "attaching gdb". How exactly this is done depends on the part that +crashes: +- master daemon. Actually you should never need to attach to it, as + you can start it within the debugger already: + # gdb --args kdm -nodaemon -debug 7 + (gdb) run +- display subdaemon. Find (using ps) the process with a name like + "-:0" (where :0 is actually the display this process is for). This + process' PPID is the master daemon. Attach to it this way: + # gdb kdm <the PID you found> + (gdb) cont + If the subdaemon crashes before you can attach, add 16 to the debug flags + when you start KDM. +- config reader. You will have to add 32 to the debug flags almost certainly. + The PPID will be the master daemon as well. + # gdb kdm_config $(pidof kdm_config) + (gdb) cont +- greeter. If it's too fast, add 64 to -debug. The PPID will be the subdaemon. + # gdb kdm_greet $(pidof kdm_greet) + (gdb) cont + The simplification with "pidof" works only if you have only one display, + otherwise you have to find the PID manually (by using ps -fx). +Once you got gdb attached to the offending process, do whatever is needed +to make it crash (probably nothing, if you had to use a delay parameter). +Once it crashed, gdb will tell you a signal name, like SIGSEGV - that's the +first interesting part for me. Then you have to create the actual backtrace: + (gdb) bt +The output of this command is interesting for me. +I might request a backtrace even if nothing crashes, but instead hangs. In +this case don't use "cont" after attaching, but use "bt" right away. If the +process is already running, interrupt it with ctrl-c. +For obvious reasons you have to run gdb on a different virtual terminal than +the X server. To get there, press alt-ctrl-f1 and log in as root. To +switch to the X server's vt, press alt-ctrl-f7 (the exact function key may +be different on your system). You may also use a remote login from a +second machine. In any case it is advantageous to have mouse support on the +debugging console for copying the backtrace. +Note that a backtrace is usually _much_ more useful if the binary contains +debugging info, so you should install from source with the --enable-debug +configure flag if at all possible. + + +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-2003 Oswald Buddenhagen <ossi@kde.org> + +The files in the backend directory are licensed under the X licence +(see http://www.x.org/Downloads_terms.html for more info). +The files in the kfrontend directory 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 with the autoconf stuff. +Martin Baehr for intensive testing and writing the sample Xsession scripts. +Harald Hoyer <Harald.Hoyer@redhat.de> for the (now obsoleted) chooser. +SuSE for employing me (ossi) for three months to work on kdm. +BasysKom for sponsoring my (ossi's) work on the conversation plugin stuff. +... and _many_ others ... + + +-- +Have fun with it (and feel free to comment), + + Oswald Buddenhagen <ossi@kde.org> |