workspace/ksmserver/README

   1 KDE session manager  (ksmserver)
   2 --------------------------------
   3
   4 Matthias Ettrich <ettrich@kde.org>
   5 Lubos Lunak <l.lunak@kde.org>
   6
   7 ksmserver is KDE's session management server. It talks the
   8 standard X11R6 session management protocol (XSMP).  Thus, in theory,
   9 it should be compatible with all session managment compliant X11R6
  10 applications. Unfortunately, there aren't that many of them. To be
  11 precise, I have never seen a single commercial application that
  12 supports it and even within the official X11R6 distribution, 'xclock'
  13 is the only exception. Nevertheless we've chosen to support XSMP
  14 despites the complexity of the protocol in order to provide KDE users
  15 more interoperability with applications that were not explicitely
  16 written with KDE in mind. XSMP, as an official X standard, promised to
  17 be more likely to be supported by third parties than even a superior
  18 KDE-specific protocol. Let's see whether we were right and more
  19 applications will actually talk XSMP. At least all KDE applications do
  20 now.
  21
  22 Here's a short overview on how session management works.
  23
  24 Contents
  25 --------
  26
  27 Starting the server
  28 KDE startup sequence
  29 Establishing the connection
  30 Authorization
  31 Requesting a shutdown
  32
  33
  34 Starting the server
  35 -------------------
  36
  37 The server is usually started from the 'startkde' script. It supports the following options:
  38
  39   -r, --restore             Restores the previous session if available
  40   -w, --windowmanager <wm>  Starts 'wm' in case no other window manager is
  41                             participating in the session. Default is 'kwin'
  42
  43 The default 'startkde' launches 'ksmserver --restore'.  The
  44 'windowmanager' option is useful for users that prefer a window
  45 manager other than kwin. Since the window manager has to participate
  46 in the session (it has to remember window positions and states), it is
  47 usually restarted when the session is restored. To be *really* sure
  48 that this happens, even if the wm might have crashed during the
  49 previous session, ksmserver ensures that. The option specifies, which
  50 windowmanager shall be launched for sure. But again: if the stored
  51 session contains a window manager, the restored one will be used, not
  52 the specified one. As a special feature, ksmserver always starts the
  53 specified window manager first, which results in a much nicer startup
  54 sequence (less flashy).
  55
  56 KDE startup sequence
  57 --------------------
  58
  59 Ksmserver controls the second part of the KDE startup sequence,
  60 after it gets control from the startkde script, which controls
  61 the first part of the startup sequence. All code related to startup
  62 should be in startup.cpp and going down in that source file should
  63 follow the startup order (but note that this is just a documentation
  64 which may get outdated, so in case of doubts the source wins ;) ).
  65
  66 The startkde scripts already launches kdeinit, which in turns launches
  67 KDE daemons like dbus daemon, klauncher and kded. Kded loads autoloaded
  68 kded modules, i.e. those that have X-KDE-Kded-autoload=true in .desktop
  69 files. The exact way autoloading works is controlled by X-KDE-Kded-phase=,
  70 which may be 0, 1 or 2 (the default). Kded phase 0 means the module is
  71 always loaded by kded, even outside of KDE session. It should used only
  72 by kded modules which must be always running. Kded phase 1 modules are
  73 loaded right after kded startup, but only during KDE startup, i.e. it is
  74 for modules that are always needed by the KDE session. Phase 2 modules
  75 will be loaded later. [More information about kded modules could be
  76 found in kdelibs/kded/HOWTO]
  77
  78 Startkde also launches kcminit, which performs initialization done by kcontrol
  79 modules. There are three kcminit phases, 0, 1 and 2, controlled
  80 by X-KDE-Init-Phase= in the .desktop file, which defaults to 1. Phase 0 kcminit
  81 modules should be only those that really need to be run early in the startup
  82 process (and those should probably actually use kstartupconfig in startkde
  83 to be done even before kdeinit and daemons). After executing phase 0
  84 modules kcminit returns and waits.
  85
  86 When ksmserver is launched, the first thing it does is launching
  87 the window manager, as the WM is necessary before any windows are possibly
  88 shown. When the WM is ready, ksmserver tells klauncher to perform autostart
  89 phase 0 ($KDEHOME/share/autostart). There are 3 autostart phases, 0, 1 and 2,
  90 defined by X-KDE-autostart-phase, defaulting to 2. Phase 0 is reserved only
  91 for the actual visible base components of KDE, i.e. Plasma, in order to make
  92 the startup appear visually faster. Plasma uses D-Bus calls suspendStartup()
  93 and resumeStartup() to make ksmserver stay waiting for autostart phase 0
  94 until Plasma is ready (note: suspendStartup() needs to be called before
  95 the application registers with ksmserver, i.e. before KApplication ctor is called).
  96
  97 Next step is telling the waiting kcminit to perform phase 1 - all kcminit
  98 modules that should be executed before KDE startup is considered done.
  99 After that ksmserver tells klauncher to perform autostart phase 1,
 100 i.e. launching normal components of KDE that should be available right
 101 after KDE startup, and after this session restore is performed,
 102 i.e. launching all applications that were running during last session
 103 saving (usually logout).
 104
 105 By this time KDE session is considered to be more or less ready and
 106 ksmserver does the knotify startkde event (i.e. plays the login sound).
 107 It also tells klauncher to perform autostart phase 2, kded to load all
 108 remaining autoload (i.e. kded phase 2) modules, kcminit to execute
 109 kcminit phase 2 (kcontrol modules that do initialization that can wait,
 110 like launching daemons) and it itself executes the user Autostart folder.
 111
 112 Technical note: There's a reason why kded modules and items in autostart
 113 default to the latest phase. Before you explicitly use a different phase,
 114 read and understand what's above. You should also consider whether something
 115 really needs to be launched during KDE startup and can't be loaded on-demand
 116 when really needed. Abusing the phases will result in public spanking
 117 for making KDE startup slower.
 118
 119
 120 Establishing the connection
 121 ---------------------------
 122
 123 As required by the XSMP specification, the session management server
 124 propagates its network address in the SESSION_MANAGER environment
 125 variable. Probably not the best way to do it, but it's the way it
 126 is. All KDE (and plain Qt) applications simply read this variable and
 127 try to establish a connection to an XSMP server at this address. If
 128 the variable is undefined, nothing happens.
 129
 130 This means, if you want to start a program that should not participate
 131 in the session, simply undefine SESSION_MANAGER in your terminal
 132 window and launch the application. If you want to see an application
 133 desparately trying to connect to something, try setting it to some
 134 bogus value.
 135
 136 In addition, ksmserver propagates both its network address and its
 137 process id in ~/.kde/socket-$HOSTNAME/KSMserver-$DISPLAY. A
 138 utility function KWorkSpace::propagateSessionManager() reads this
 139 setting and sets SESSION_MANAGER accordingly, so that child processes
 140 can pick it up.  The function is called by clients that are started
 141 outside the session (i.e. before ksmserver is started), but want to
 142 launch other processes that should participate in the session.
 143
 144 Authorization
 145 -------------
 146
 147 XSMP is built on top of the Inter Client Exchange (ICE) protocol,
 148 which comes standard as a part of X11R6 and later.
 149 Authorization is done using 'iceauth', with MIT-MAGIC-COOKIE as used
 150 by X. In order to be able to access the session management server, you
 151 need to be able to read ~/.ICEauthority. For security reasons, we do
 152 not provide any host-based authorization.
 153
 154
 155 Requesting a shutdown
 156 ---------------------
 157
 158 If an application wants to request a shutdown (i.e. a logout), it does
 159 this via an SmcRequestSaveYourself message to the server. In KDE, a
 160 utility function KWorkSpace::requestShutDown() does exactly
 161 this. It's for example called by KDE's panel or by the context menu of
 162 the desktop.