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 is 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:
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:
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.
Reverse the effect of lock, and re-enable auto-relogin.
The currently running session is forcibly terminated. No auto-relogin is attempted, but a scheduled "login" command will be executed.
Commands for all sockets
Returns a list of this socket's capabilities:
identifies kdm, in case some other DM implements this protocol, too
The respective command is supported
The listbootoptions command and the
=
to shutdown are supported
shutdown is supported and allowed for the listed users (a comma separated list.) * means all authenticated users.
Forced shutdown may be performed by the listed users.
Forced shutdown may be performed by everybody
Reserve displays are configured, and number are available at this time
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.
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.
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.
List available boot options.
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.
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.
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
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team