2
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
4
<!ENTITY kappname "&kdesu;">
5
<!ENTITY package "kdebase">
6
<!ENTITY % addindex "IGNORE">
7
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
10
<book id="kdesu" lang="&language;">
13
<title>The &kdesu; handbook</title>
16
<author>&Geert.Jansen; &Geert.Jansen.mail;</author>
17
<!-- TRANS:ROLES_OF_TRANSLATORS -->
22
<holder>&Geert.Jansen;</holder>
25
<legalnotice>&FDLNotice;</legalnotice>
27
<date>2010-09-21</date>
28
<releaseinfo>&kde; 4.5</releaseinfo>
31
<abstract><para>&kdesu; is a graphical front end for the &UNIX;
32
<command>su</command> command.</para></abstract>
35
<keyword>KDE</keyword>
37
<keyword>password</keyword>
38
<keyword>root</keyword>
43
<chapter id="introduction">
44
<title>Introduction</title>
46
<!-- from kdebase/runtime/kdesu/FAQ since rev 855297
47
kdesu is a libexec program, so does not normally reside in your PATH.
49
<command>$(kde4-config - -path libexec)kdesu - - program_to_run
51
https://bugs.kde.org/show_bug.cgi?id=194267
52
"one needs to create a
53
~/.kde/share/config/kdesurc file to tell KDE to use sudo instead of su."
54
~/.kde/share/config/kdesurc
56
super-user-command=sudo
57
does this really work?
60
<para>Welcome to &kdesu;! &kdesu; is a graphical front end for the
61
&UNIX; <command>su</command> command for the K Desktop Environment.
62
It allows you to run a program as different user by supplying the
63
password for that user. &kdesu; is an unprivileged program; it uses
64
the system's <command>su</command>.</para>
66
<para>&kdesu; has one additional feature: it can remember passwords
67
for you. If you are using this feature, you only need to enter the
68
password once for each command. See <xref
69
linkend="sec-password-keeping"/> for more information on this and a
70
security analysis.</para>
72
<para>This program is meant to be started from the command line or
73
from <filename>.desktop</filename> files. Although it asks for the
74
<systemitem class="username">root</systemitem> password using a &GUI;
75
dialog, I consider it to be more of a command line <-> &GUI;
76
glue instead of a pure &GUI; program.</para>
78
<para>Since <command>kdesu</command> is no longer installed in <userinput>
79
$(kde4-config --prefix)</userinput>/bin but in <userinput>kde4-config --path libexec</userinput>
80
and therefore not in your <envar>Path</envar>, you have to use <userinput>$(kde4-config
81
--path libexec)<command>kdesu</command></userinput> to launch <command>kdesu</command>.</para>
84
<chapter id="using-kdesu">
85
<title>Using &kdesu;</title>
87
<para>Usage of &kdesu; is easy. The syntax is like this:</para>
90
<command>kdesu</command>
92
<group choice="opt"><option>-c</option> <replaceable> command</replaceable></group>
93
<group choice="opt"><option>-d</option></group>
94
<group choice="opt"><option>-f</option> <replaceable> file</replaceable></group>
95
<group choice="opt"><option>-i</option> <replaceable> icon name</replaceable></group>
96
<group choice="opt"><option>-n</option></group>
97
<group choice="opt"><option>-p</option> <replaceable> priority</replaceable></group>
98
<group choice="opt"><option>-r</option></group>
99
<group choice="opt"><option>-s</option></group>
100
<group choice="opt"><option>-t</option></group>
101
<group choice="opt"><option>-u</option> <replaceable> user</replaceable></group>
102
<group choice="opt"><option>--noignorebutton</option></group>
103
<group choice="opt"><option>--attach</option> <replaceable> winid</replaceable></group>
104
<!--group choice="opt"><option>- -nonewdcop</option></group>
106
<group><arg choice="req"><replaceable>command</replaceable> <arg><replaceable>arg1</replaceable></arg>
107
<arg><replaceable>arg2</replaceable></arg>
108
<arg rep="repeat"><replaceable></replaceable></arg></arg></group-->
111
<command>kdesu</command>
112
<arg choice="opt">&kde; Generic Options</arg>
113
<arg choice="opt">&Qt; Generic Options</arg>
116
<para>The command line options are explained below.</para>
120
<term><option>-c <replaceable>command</replaceable></option></term>
121
<listitem><para>This specifies the command to run as root. It has to be passed
122
in one argument. So if, for example, you want to start a new file manager, you
123
would enter at the prompt: <userinput>$(kde4-config --path libexec)<command>kdesu <option>-c <replaceable>
124
&dolphin;</replaceable></option></command></userinput></para></listitem>
127
<term><option>-d</option></term>
128
<listitem><para>Show debug information.</para></listitem>
131
<term><option>-f <replaceable>file</replaceable></option></term>
132
<listitem><para>This option allow efficient use of &kdesu; in
133
<filename>.desktop</filename> files. It tells &kdesu; to examine the
134
file specified by <parameter>file</parameter>. If this file is
135
writable by the current user, &kdesu; will execute the command as the
136
current user. If it is not writable, the command is executed as user
137
<parameter>user</parameter> (defaults to root).</para>
138
<para><parameter>file</parameter> is evaluated like this: if
139
<parameter>file</parameter> starts with a <literal>/</literal>, it is
140
taken as an absolute filename. Otherwise, it is taken as the name of a
141
global &kde; configuration file.</para></listitem>
144
<term><option>-i</option> <replaceable>icon name</replaceable></term>
145
<listitem><para>Specify icon to use in the password dialog. You may specify
146
just the name, without any extension.</para>
147
<para>For instance to run &konqueror; in filemanager mode and show the
148
&konqueror; icon in the password dialog:</para>
149
<screen><userinput>$(kde4-config --path libexec)<command>kdesu</command> <option>-i konqueror</option>
150
<option>-c "konqueror --profile filemanagement"</option></userinput></screen>
155
<term><option>-n</option></term>
156
<listitem><para>Do not keep the password. This disables the <guilabel>keep
157
password</guilabel> checkbox in the password dialog.</para></listitem>
160
<term><option>-p</option> <replaceable>priority</replaceable></term>
162
<para>Set priority value. The priority is an arbitrary number between 0 and
163
100, where 100 means highest priority, and 0 means lowest. The default is
168
<term><option>-r</option></term>
169
<listitem><para>Use realtime scheduling.</para>
174
<term><option>-s</option></term>
175
<listitem><para>Stop the kdesu daemon. See <xref
176
linkend="sec-password-keeping"/>.</para></listitem>
179
<term><option>-t</option></term>
180
<listitem><para>Enable terminal output. This disables password keeping. This is
181
largely for debugging purposes; if you want to run a console mode app, use the
182
standard <command>su</command> instead.</para> </listitem>
185
<term><option>-u</option> <replaceable> user</replaceable></term>
186
<listitem><para>While the most common use for &kdesu; is to run a command as
187
the superuser, you can supply any user name and the appropriate
196
<chapter id="Internals">
197
<title>Internals</title>
199
<sect1 id="x-authentication">
200
<title>X authentication</title>
202
<para>The program you execute will run under the root user id and will
203
generally have no authority to access your X display. &kdesu; gets
204
around this by adding an authentication cookie for your display to a
205
temporary <filename>.Xauthority</filename> file. After the command
206
exits, this file is removed. </para>
208
<para>If you don't use X cookies, you are on your own. &kdesu; will
209
detect this and will not add a cookie but you will have to make sure
210
that root is allowed to access to your display.</para>
214
<sect1 id="interface-to-su">
215
<title>Interface to <command>su</command></title>
217
<para>&kdesu; uses the sytem's <command>su</command> for acquiring
218
priviliges. In this section, I explain the details of how &kdesu; does
221
<para>Because some <command>su</command> implementations (&ie; the one
222
from &RedHat;) don't want to read the password from
223
<literal>stdin</literal>, &kdesu; creates a pty/tty pair and executes
224
<command>su</command> with its standard filedescriptors connected to
227
<para>To execute the command the user selected, rather than an
228
interactive shell, &kdesu; uses the <option>-c</option> argument with
229
<command>su</command>. This argument is understood by every shell that
230
I know of so it should work portably. <command>su</command> passes
231
this <option>-c</option> argument to the target user's shell, and the
232
shell executes the program. Example command: <command>su <option>root
233
-c <replaceable>the_program</replaceable></option></command>.</para>
235
<para>Instead of executing the user command directly with
236
<command>su</command>, &kdesu; executes a little stub program called
237
<application>kdesu_stub</application>. This stub (running as the
238
target user), requests some information from &kdesu; over the pty/tty
239
channel (the stub's stdin and stdout) and then executes the user's
240
program. The information passed over is: the X display, an X
241
authentication cookie (if available), the <envar>PATH</envar> and the
242
command to run. The reason why a stub program is used is that the X
243
cookie is private information and therefore cannot be passed on the
248
<sect1 id="password-checking">
249
<title>Password Checking</title>
251
<para>&kdesu; will check the password you entered and gives an error
252
message if it is not correct. The checking is done by executing a test
253
program: <filename>/bin/true</filename>. If this succeeds, the
254
password is assumed to be correct.</para>
258
<sect1 id="sec-password-keeping">
259
<title>Password Keeping</title>
261
<para>For your comfort, &kdesu; implements a <quote>keep
262
password</quote> feature. If you are interested in security, you
263
should read this paragraph.</para>
265
<para>Allowing &kdesu; to remember passwords opens up a (small)
266
security hole in your system. Obviously, &kdesu; does not allow
267
anybody but your user id to use the passwords, but, if done without
268
caution, this would lowers <systemitem
269
class="username">root</systemitem>'s security level to that of a
270
normal user (you). A hacker who breaks into your account, would get
271
<systemitem class="username">root</systemitem> access. &kdesu; tries
272
to prevent this. The security scheme it uses is, in my opinion at
273
least, reasonably safe and is explained here.</para>
275
<para>&kdesu; uses a daemon, called
276
<application>kdesud</application>. The daemon listens to a &UNIX;
277
socket in <filename>/tmp</filename> for commands. The mode of the
278
socket is 0600 so that only your user id can connect to it. If
279
password keeping is enabled, &kdesu; executes commands through this
280
daemon. It writes the command and <systemitem
281
class="username">root</systemitem>'s password to the socket and the
282
daemon executes the command using <command>su</command>, as describe
283
before. After this, the command and the password are not thrown
284
away. Instead, they are kept for a specified amount of time. This is
285
the timeout value from in the control module. If another request for
286
the same command is coming within this time period, the client does
287
not have to supply the password. To keep hackers who broke into your
288
account from stealing passwords from the daemon (for example, by
289
attaching a debugger), the daemon is installed set-group-id
290
nogroup. This should prevent all normal users (including you) from
291
getting passwords from the <application>kdesud</application>
292
process. Also, the daemon sets the <envar>DISPLAY</envar> environment
293
variable to the value it had when it was started. The only thing a
294
hacker can do is execute an application on your display.</para>
296
<para>One weak spot in this scheme is that the programs you execute
297
are probably not written with security in mind (like setuid
298
<systemitem class="username">root</systemitem> programs). This means
299
that they might have buffer overruns or other problems and a hacker
300
could exploit those.</para>
302
<para>The use of the password keeping feature is a tradeoff between
303
security and comfort. I encourage you to think it over and decide for
304
yourself if you want to use it or not.</para>
309
<chapter id="Author">
310
<title>Author</title>
314
<para>Copyright 2000 &Geert.Jansen;</para>
316
<para>&kdesu; is written by &Geert.Jansen;. It is somewhat based on
317
Pietro Iglio's &kdesu;, version 0.3. Pietro and I agreed that I will
318
maintain this program in the future.</para>
320
<para>The author can be reached through email at &Geert.Jansen.mail;.
321
Please report any bugs you find to me so that I can fix them. If you
322
have a suggestion, feel free to contact me.</para>
324
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
327
&underArtisticLicense;
added
removed
doc/en_US/kdesu/index.docbook
