runtime/doc/kdesu/index.docbook

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
   3 "dtd/kdex.dtd" [
   4   <!ENTITY kappname "&kdesu;">
   5   <!ENTITY package "kdebase">
   6   <!ENTITY % addindex "IGNORE">
   7   <!ENTITY % English "INCLUDE" > <!-- change language only here -->
   8 ]>
   9
  10 <book lang="&language;">
  11 <bookinfo>
  12
  13 <title>The &kdesu; handbook</title>
  14
  15 <authorgroup>
  16 <author>&Geert.Jansen; &Geert.Jansen.mail;</author>
  17 <!-- TRANS:ROLES_OF_TRANSLATORS -->
  18 </authorgroup>
  19
  20 <copyright>
  21 <year>2000</year>
  22 <holder>&Geert.Jansen;</holder>
  23 </copyright>
  24
  25 <legalnotice>&FDLNotice;</legalnotice>
  26
  27 <date>2005-06-07</date>
  28 <releaseinfo>1.00.00</releaseinfo>
  29
  30
  31 <abstract><para>&kdesu; is a graphical front end for the &UNIX;
  32 <command>su</command> command.</para></abstract>
  33
  34 <keywordset>
  35 <keyword>KDE</keyword>
  36 <keyword>su</keyword>
  37 <keyword>password</keyword>
  38 <keyword>root</keyword>
  39 </keywordset>
  40
  41 </bookinfo>
  42
  43 <chapter id="introduction">
  44 <title>Introduction</title>
  45
  46 <para>Welcome to &kdesu;! &kdesu; is a graphical front end for the
  47 &UNIX; <command>su</command> command for the K Desktop Environment.
  48 It allows you to run a program as different user by supplying the
  49 password for that user. &kdesu; is an unprivileged program; it uses
  50 the system's <command>su</command>.</para>
  51
  52 <para>&kdesu; has one additional feature: it can remember passwords
  53 for you. If you are using this feature, you only need to enter the
  54 password once for each command. See <xref
  55 linkend="sec-password-keeping"/> for more information on this and a
  56 security analysis.</para>
  57
  58 <para>This program is meant to be started from the command line or
  59 from <filename>.desktop</filename> files. Although it asks for the
  60 <systemitem class="username">root</systemitem> password using a &GUI;
  61 dialog, I consider it to be more of a command line &lt;-&gt; &GUI;
  62 glue instead of a pure &GUI; program.</para>
  63
  64 </chapter>
  65
  66 <chapter id="using-kdesu">
  67 <title>Using &kdesu;</title>
  68
  69 <para>Usage of &kdesu; is easy. The syntax is like this:</para>
  70
  71 <cmdsynopsis>
  72 <command>kdesu</command>
  73
  74 <group choice="opt"><option>-c</option></group>
  75 <group choice="opt"><option>-d</option></group>
  76 <group choice="opt"><option>-f</option> <replaceable> file</replaceable></group>
  77 <group choice="opt"><option>-i</option> <replaceable> icon name</replaceable></group>
  78 <group choice="opt"><option>-n</option></group>
  79 <group choice="opt"><option>-p</option> <replaceable> priority</replaceable></group>
  80 <group choice="opt"><option>-r</option></group>
  81 <group choice="opt"><option>-s</option></group>
  82 <group choice="opt"><option>-t</option></group>
  83 <group choice="opt"><option>-u</option> <replaceable>
  84 user</replaceable></group>
  85 <group choice="opt"><option>--nonewdcop</option></group>
  86
  87 <group><arg choice="req"><replaceable>command</replaceable> <arg><replaceable>arg1</replaceable></arg>
  88           <arg><replaceable>arg2</replaceable></arg>
  89           <arg rep="repeat"><replaceable></replaceable></arg></arg></group>
  90 </cmdsynopsis>
  91 <cmdsynopsis>
  92 <command>kdesu</command>
  93 <arg choice="opt">&kde; Generic Options</arg>
  94 <arg choice="opt">Qt Generic Options</arg>
  95 </cmdsynopsis>
  96
  97 <para>The command line options are explained below.</para>
  98
  99 <variablelist>
 100 <varlistentry>
 101 <term><option>-c <replaceable>program</replaceable></option></term>
 102 <listitem><para>This specifies the program to run as root. It has to be passed
 103 in one argument. So if, for example, you want to start a new file manager, you
 104 would enter at the prompt: <userinput><command>kdesu <option>-c <replaceable>kfm
 105 -sw</replaceable></option></command></userinput></para></listitem>
 106 </varlistentry>
 107 <varlistentry>
 108 <term><option>-d</option></term>
 109 <listitem><para>Do not show the command to be run in the dialog.</para></listitem>
 110 </varlistentry>
 111 <varlistentry>
 112 <term><option>-f <replaceable>file</replaceable></option></term>
 113 <listitem><para>This option allow efficient use of &kdesu; in
 114 <filename>.desktop</filename> files. It tells &kdesu; to examine the
 115 file specified by <parameter>file</parameter>. If this file is
 116 writable by the current user, &kdesu; will execute the command as the
 117 current user. If it is not writable, the command is executed as user
 118 <parameter>user</parameter> (defaults to root).</para>
 119 <para><parameter>file</parameter> is evaluated like this: if
 120 <parameter>FILE</parameter> starts with a <literal>/</literal>, it is
 121 taken as an absolute filename. Otherwise, it is taken as the name of a
 122 global &kde; configuration file. For example: to configure the K display
 123 manager, <application>kdm</application>, you could issue
 124 <command>kdesu <option>-c kdmconfig -f
 125 kdmrc</option></command></para></listitem>
 126 </varlistentry>
 127 <varlistentry>
 128 <term><option>-i</option> <replaceable>icon name</replaceable></term>
 129 <listitem><para>Specify icon to use in the password dialog.  You may specify
 130 just the name, without any extension.</para>
 131 <para>For instance to run <command>kfmclient</command> and show the
 132 &konqueror; icon in the password dialog:</para>
 133 <screen><userinput><command>kdesu</command>  <option>-i konqueror</option> <command>kfmclient</command></userinput></screen>
 134 </listitem>
 135 </varlistentry>
 136
 137 <varlistentry>
 138 <term><option>-n</option></term>
 139 <listitem><para>Do not keep the password. This disables the <guilabel>keep
 140 password</guilabel> checkbox in the password dialog.</para></listitem>
 141 </varlistentry>
 142 <varlistentry>
 143 <term><option>-p</option> <replaceable>priority</replaceable></term>
 144 <listitem>
 145 <para>Set priority value.  The priority is an arbitrary number between 0 and
 146 100, where 100 means highest priority, and 0 means lowest.  The default is
 147 50.</para>
 148 </listitem>
 149 </varlistentry>
 150 <varlistentry>
 151 <term><option>-r</option></term>
 152 <listitem><para>Use realtime scheduling.</para>
 153 </listitem>
 154 </varlistentry>
 155
 156 <varlistentry>
 157 <term><option>-s</option></term>
 158 <listitem><para>Stop the kdesu daemon. See <xref
 159 linkend="sec-password-keeping"/>.</para></listitem>
 160 </varlistentry>
 161 <varlistentry>
 162 <term><option>-t</option></term>
 163 <listitem><para>Enable terminal output. This disables password keeping. This is
 164 largely for debugging purposes; if you want to run a console mode app, use the
 165 standard <command>su</command> instead.</para> </listitem>
 166 </varlistentry>
 167 <varlistentry>
 168 <term><option>-u</option> <replaceable> user</replaceable></term>
 169 <listitem><para>While the most common use for &kdesu; is to run a command as
 170 the superuser, you can supply any user name and the appropriate
 171 password.</para>
 172 </listitem>
 173 </varlistentry>
 174
 175 </variablelist>
 176
 177 </chapter>
 178
 179 <chapter id="Internals">
 180 <title>Internals</title>
 181
 182 <sect1 id="x-authentication">
 183 <title>X authentication</title>
 184
 185 <para>The program you execute will run under the root user id and will
 186 generally have no authority to access your X display. &kdesu; gets
 187 around this by adding an authentication cookie for your display to a
 188 temporary <filename>.Xauthority</filename> file. After the command
 189 exits, this file is removed. </para>
 190
 191 <para>If you don't use X cookies, you are on your own. &kdesu; will
 192 detect this and will not add a cookie but you will have to make sure
 193 that root is allowed to access to your display.</para>
 194
 195 </sect1>
 196
 197 <sect1 id="interface-to-su">
 198 <title>Interface to <command>su</command></title>
 199
 200 <para>&kdesu; uses the sytem's <command>su</command> for acquiring
 201 priviliges. In this section, I explain the details of how &kdesu; does
 202 this. </para>
 203
 204 <para>Because some <command>su</command> implementations (&ie; the one
 205 from &RedHat;) don't want to read the password from
 206 <literal>stdin</literal>, &kdesu; creates a pty/tty pair and executes
 207 <command>su</command> with its standard filedescriptors connected to
 208 the tty.</para>
 209
 210 <para>To execute the command the user selected, rather than an
 211 interactive shell, &kdesu; uses the <option>-c</option> argument with
 212 <command>su</command>. This argument is understood by every shell that
 213 I know of so it should work portably. <command>su</command> passes
 214 this <option>-c</option> argument to the target user's shell, and the
 215 shell executes the program. Example command: <command>su <option>root
 216 -c <replaceable>the_program</replaceable></option></command>.</para>
 217
 218 <para>Instead of executing the user command directly with
 219 <command>su</command>, &kdesu; executes a little stub program called
 220 <application>kdesu_stub</application>. This stub (running as the
 221 target user), requests some information from &kdesu; over the pty/tty
 222 channel (the stub's stdin and stdout) and then executes the user's
 223 program. The information passed over is: the X display, an X
 224 authentication cookie (if available), the <envar>PATH</envar> and the
 225 command to run. The reason why a stub program is used is that the X
 226 cookie is private information and therefore cannot be passed on the
 227 command line.</para>
 228
 229 </sect1>
 230
 231 <sect1 id="password-checking">
 232 <title>Password Checking</title>
 233
 234 <para>&kdesu; will check the password you entered and gives an error
 235 message if it is not correct. The checking is done by executing a test
 236 program: <filename>/bin/true</filename>. If this succeeds, the
 237 password is assumed to be correct.</para>
 238
 239 </sect1>
 240
 241 <sect1 id="sec-password-keeping">
 242 <title>Password Keeping</title>
 243
 244 <para>For your comfort, &kdesu; implements a <quote>keep
 245 password</quote> feature. If you are interested in security, you
 246 should read this paragraph.</para>
 247
 248 <para>Allowing &kdesu; to remember passwords opens up a (small)
 249 security hole in your system. Obviously, &kdesu; does not allow
 250 anybody but your user id to use the passwords, but, if done without
 251 caution, this would lowers <systemitem
 252 class="username">root</systemitem>'s security level to that of a
 253 normal user (you). A hacker who breaks into your account, would get
 254 <systemitem class="username">root</systemitem> access. &kdesu; tries
 255 to prevent this. The security scheme it uses is, in my opinion at
 256 least, reasonably safe and is explained here.</para>
 257
 258 <para>&kdesu; uses a daemon, called
 259 <application>kdesud</application>. The daemon listens to a &UNIX;
 260 socket in <filename>/tmp</filename> for commands. The mode of the
 261 socket is 0600 so that only your user id can connect to it. If
 262 password keeping is enabled, &kdesu; executes commands through this
 263 daemon. It writes the command and <systemitem
 264 class="username">root</systemitem>'s password to the socket and the
 265 daemon executes the command using <command>su</command>, as describe
 266 before. After this, the command and the password are not thrown
 267 away. Instead, they are kept for a specified amount of time. This is
 268 the timeout value from in the control module.  If another request for
 269 the same command is coming within this time period, the client does
 270 not have to supply the password. To keep hackers who broke into your
 271 account from stealing passwords from the daemon (for example, by
 272 attaching a debugger), the daemon is installed set-group-id
 273 nogroup. This should prevent all normal users (including you) from
 274 getting passwords from the <application>kdesud</application>
 275 process. Also, the daemon sets the <envar>DISPLAY</envar> environment
 276 variable to the value it had when it was started. The only thing a
 277 hacker can do is execute an application on your display.</para>
 278
 279 <para>One weak spot in this scheme is that the programs you execute
 280 are probably not written with security in mind (like setuid
 281 <systemitem class="username">root</systemitem> programs). This means
 282 that they might have buffer overruns or other problems and a hacker
 283 could exploit those.</para>
 284
 285 <para>The use of the password keeping feature is a tradeoff between
 286 security and comfort. I encourage you to think it over and decide for
 287 yourself if you want to use it or not.</para>
 288
 289 </sect1>
 290 </chapter>
 291
 292 <chapter id="Author">
 293 <title>Author</title>
 294
 295 <para>&kdesu;</para>
 296
 297 <para>Copyright 2000 &Geert.Jansen;</para>
 298
 299 <para>&kdesu; is written by &Geert.Jansen;. It is somewhat based on
 300 Pietro Iglio's &kdesu;, version 0.3. Pietro and I agreed that I will
 301 maintain this program in the future.</para>
 302
 303 <para>The author can be reached through email at &Geert.Jansen.mail;.
 304 Please report any bugs you find to me so that I can fix them. If you
 305 have a suggestion, feel free to contact me.</para>
 306
 307 &underFDL;
 308 &underArtisticLicense;
 309
 310 </chapter>
 311
 312 </book>
 313 <!--
 314 Local Variables:
 315 mode: sgml
 316 sgml-omittag: nil
 317 sgml-shorttag: t
 318 End:
 319 -->
 320