Index: index.docbook =================================================================== RCS file: /home/kde/kdebase/doc/kdm/index.docbook,v retrieving revision 1.37 diff -u -3 -p -r1.37 index.docbook --- index.docbook 19 Jan 2005 19:36:37 -0000 1.37 +++ index.docbook 6 Feb 2005 21:04:23 -0000 @@ -4,6 +4,8 @@ kdmrc"> + ksmserver"> + kdesktop"> XDMCP"> xdm"> @@ -68,11 +70,10 @@ is also known as the Login Manage Introduction - &kdm; provides a graphical interface that allows you to log in -to a system. It prompts for login (username) and password, -authenticates the user and starts a session. &kdm; is -superior to &xdm;, the X Display Manager, in -a number of ways. +&kdm; provides a graphical interface that allows you to log in to a +system. It prompts for login (username) and password, authenticates the user +and starts a session. &kdm; is superior to &xdm;, the X +Display Manager, in a number of ways. @@ -109,16 +110,16 @@ their choice. -This scenario will be sufficient for many environments where a -single user or several users normally boot the computer and log into -their preferred environment. +This scenario will be sufficient for many environments where a single +user or several users normally boot the computer and log into their +preferred environment. Setting up a Default Session Create or open the file ~/.xinitrc -If you already have a working ~/.xinitrc, -go to the next step +If you already have a working ~/.xinitrc, go to +the next step If one does not already exist, add a line to the @@ -134,30 +135,28 @@ look in their documentation for the corr -At this point, typing -startx on the commandline -should start X, with a &kde; session. The next task is to try -&kdm;. +At this point, typing startx +on the commandline should start X, with a &kde; session. The next task is +to try &kdm;. As root, type kdm at the prompt. -You should see a login window, which is described more fully -in. +You should see a login window, which is described more fully in. -Typing your normal username and password in the fields provided, -and leaving selected as the session type -should now open a &kde; session for your user. +Typing your normal username and password in the fields provided, and +leaving selected as the session type should now +open a &kde; session for your user. -If you have other users to configure, you should repeat the -procedure above for each of them. +If you have other users to configure, you should repeat the procedure +above for each of them. -This is a quick guide to getting up and running only. You -probably will want to customize &kdm; further, for example, to hide -the names of the system accounts, to allow further sessions, and much -more. Please read through the rest of this manual to find out how to -do these things. +This is a quick guide to getting up and running only. You probably +will want to customize &kdm; further, for example, to hide the names of the +system accounts, to allow further sessions, and much more. Please read +through the rest of this manual to find out how to do these things. @@ -165,8 +164,8 @@ do these things. The Login Window - The user interface to &kdm; consists of two dialog boxes. -The main dialog box has these controls: + The user interface to &kdm; consists of two dialog boxes. The main +dialog box has these controls: @@ -180,16 +179,16 @@ password. -(Optionally) a graphical image of each user (for example, a -digitized photograph). Clicking on an image is equivalent to typing -the associated username into the Username: -field. (This feature is an imitation of the login box on -IRIX). +(Optionally) a graphical image of each user (for example, a digitized +photograph). Clicking on an image is equivalent to typing the associated +username into the Username: field. (This feature is an +imitation of the login box on IRIX). + -A Menu drop-down box that allows -&kdm; to be used to start sessions with various different window managers or -desktop environments installed on the system. +A Menu drop-down box that allows &kdm; to be used +to start sessions with various different window managers or desktop +environments installed on the system. @@ -202,7 +201,7 @@ either a static image or an analog clock A Login button that validates the username/password combination and attempts to start a session of the -selected type. +selected type. @@ -212,8 +211,8 @@ fields. -(Optionally) A Shutdown button that -displays the Shutdown dialog box. +(Optionally) A Shutdown button that displays +the Shutdown dialog box. A Menu button that opens an action menu @@ -221,36 +220,34 @@ with the following items: -(On local displays) a Restart X -Server item that terminates the currently running -&X-Server;, starts a new one and displays the login dialog again. You -can use this if the display content seems to be broken somehow. +(On local displays) a Restart X Server item +that terminates the currently running &X-Server;, starts a new one and +displays the login dialog again. You can use this if the display content +seems to be broken somehow. -(On remote displays) A Close -Connection item that closes the connection to the XDMCP -server you are currently connected to. If you got to this server -through a host chooser, this will bring you back to the chooser, -otherwise it will only reset the &X-Server; and bring up the login -dialog again. +(On remote displays) A Close Connection +item that closes the connection to the XDMCP server you are currently +connected to. If you got to this server through a host chooser, this will +bring you back to the chooser, otherwise it will only reset the &X-Server; +and bring up the login dialog again. (Optionally on local displays) A Console -Mode item that terminates the currently running -&X-Server; and leaves you alone with a console login. &kdm; will -resume the graphical login if nobody is logged in at the console for -some time. To make this work, you need to use the -local@<console> syntax in the Xservers -file (see comments in that file). +Mode item that terminates the currently running &X-Server; and +leaves you alone with a console login. &kdm; will resume the graphical login +if nobody is logged in at the console for some time. To make this work, you +need to use the local@<console> syntax in the +Xservers file (see comments in that file). -(Optionally) A Shutdown... button that -displays the shutdown dialog box. +(Optionally) A Shutdown... button that displays +the shutdown dialog box. @@ -259,25 +256,27 @@ radio buttons that allow one of these op -Shutdown -Shut the system down in a controlled manner, -ready for power-down. +Shutdown + +Shut the system down in a controlled manner, ready for +power-down. + Restart -Shut the system down and reboot. For systems that use -Lilo, an optional drop-down box allows you to select -a particular operating-system kernel to be used for the + +Shut the system down and reboot. For systems that use +Lilo, an optional drop-down box allows you to +select a particular operating-system kernel to be used for the reboot. Restart X Server -Stop and then restart the X-server. Typically, you might need to -use this option if you have changed your X11 configuration in some -way. - +Stop and then restart the X-server. Typically, you might need to use +this option if you have changed your X11 configuration in some way. + Console Mode @@ -285,14 +284,14 @@ way. Stop the &X-Server; and return the system to console mode. This is achieved by bringing the system down to run-level 3. Typically, the system manager might need to use this option before upgrading or re-configuring X11 -software. - +software. + -Pressing the OK button initiates the -selected action; pressing the Cancel button -returns to the main &kdm; dialog box. +Pressing the OK button initiates the selected +action; pressing the Cancel button returns to the +main &kdm; dialog box. @@ -300,15 +299,13 @@ returns to the main &kdm; dialog box. Configuring &kdm; -This chapter assumes that &kdm; is already up and running on -your system, and that you simply want to change its behavior in some -way. - -When &kdm; starts up, it reads its configuration from the -folder $KDEDIR/share/config/kdm/ (this may be -/etc/kde3/kdm/ or something -else on your system). +This chapter assumes that &kdm; is already up and running on your +system, and that you simply want to change its behavior in some way. + +When &kdm; starts up, it reads its configuration from the folder +$KDEDIR/share/config/kdm/ (this may +be /etc/kde3/kdm/ or something else +on your system). The main configuration file is &kdmrc;; all other files are referenced from there and could be stored under any name anywhere on @@ -1174,6 +1171,317 @@ this. + +Advanced Topics + + +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 =. 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 permission 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 (⪚ +perm, noent, &etc;) +followed by a longer explanation. + + +Global commands: + +login +(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, and 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 of this socket's capabilities: + + + +kdm + +identifies kdm, in case some other DM implements this protocol, +too + + + +list, lock, +suicide, login + +The respective command is supported + + + +bootoptions + +The listbootoptions command and the + to shutdown are supported + + + +shutdown <list> + +shutdown is supported and allowed for the listed +users (a comma separated list.) * means all +authenticated users. + + + +nuke <list> + +Forced shutdown may be performed by the listed users. + + + +nuke + +Forced shutdown may be performed by 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> for outgoing +remote sessions, empty for passive sessions. +A Flag field: +* for the display belonging +to the requesting socket. +! for sessions that cannot be killed by the +reqeusting socket. + + + +New fields may be added in the future. + + + + +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 (⪚ vt3) or by a display using it +(eg; :2). +Permitted only on sockets of local displays and the global +socket. + + + + +listbootoptions + +List available boot options. + + + + + +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 sessino 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. -1 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 a 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 (⪚ from within a +shell script). Try kdmctl 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 + + + Other sources of information @@ -1258,7 +1566,7 @@ Truly r