Chapter 10. Advanced Topics

Table of Contents

Command Sockets

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 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 (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.

resume

Force return from console mode, even if TTY logins are still active.

manage display [display_class [auth_name auth_data]]

Start managing the named foreign display.

display_class, if specified and non-empty, will be used for configuration matching; see Chapter 5, The Files kdm Uses for Configuration.

auth_name and auth_data need to be passed if the display requires X authorization. The format is the same as the 2nd and 3rd column of the xauth list output.

unmanage display

Stop managing the named foreign display.

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, resume, manage

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 (this is useful for a shutdown warning). 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 (this is useful for a fast user switching agent).

Each session entry is a comma separated tuple of:

  • Display or TTY name

  • VT name for local sessions, remote host name prefixed by @ for remote TTY sessions, otherwise empty

  • Logged in user's name, empty for passive sessions and outgoing remote sessions (local chooser mode)

  • Session type for active local sessions, remote hostname 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 requesting socket.

    • t for TTY sessions.

New fields may be added in the future.

reserve

Start a reserve login screen. If nobody logs in within some time, 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 (eg; :2).

Permitted only on sockets of local displays and the global socket.

listbootoptions

List available boot options.

The return value contains these tokens:

  • A list of boot options (as shown in kdm itself).

  • The default boot option.

  • The current boot option.

The default and current option are zero-based indices into the list of boot options. If either one is unset or not determinable, it is -1.

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. -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 (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