Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

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>