path: root/doc/kdesu/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [
  <!ENTITY kappname "&kdesu;">
  <!ENTITY package "kdebase">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">
<bookinfo>

<title>The &kdesu; handbook</title>

<authorgroup>
<author>&Geert.Jansen; &Geert.Jansen.mail;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2000</year>
<holder>&Geert.Jansen;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2005-06-07</date>
<releaseinfo>1.00.00</releaseinfo>


<abstract><para>&kdesu; is a graphical front end for the &UNIX;
<command>su</command> command.</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>su</keyword>
<keyword>password</keyword>
<keyword>root</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>Welcome to &kdesu;! &kdesu; is a graphical front end for the
&UNIX; <command>su</command> command for the K Desktop Environment.
It allows you to run a program as different user by supplying the
password for that user. &kdesu; is an unprivileged program; it uses
the system's <command>su</command>.</para>

<para>&kdesu; has one additional feature: it can remember passwords
for you. If you are using this feature, you only need to enter the
password once for each command. See <xref
linkend="sec-password-keeping"/> for more information on this and a
security analysis.</para>

<para>This program is meant to be started from the command line or
from <filename>.desktop</filename> files. Although it asks for the
<systemitem class="username">root</systemitem> password using a &GUI;
dialog, I consider it to be more of a command line &lt;-&gt; &GUI;
glue instead of a pure &GUI; program.</para>

</chapter>

<chapter id="using-kdesu">
<title>Using &kdesu;</title>

<para>Usage of &kdesu; is easy. The syntax is like this:</para>

<cmdsynopsis>
<command>kdesu</command>

<group choice="opt"><option>-c</option></group>
<group choice="opt"><option>-d</option></group>
<group choice="opt"><option>-f</option> <replaceable> file</replaceable></group>
<group choice="opt"><option>-i</option> <replaceable> icon name</replaceable></group>
<group choice="opt"><option>-n</option></group>
<group choice="opt"><option>-p</option> <replaceable> priority</replaceable></group>
<group choice="opt"><option>-r</option></group>
<group choice="opt"><option>-s</option></group>
<group choice="opt"><option>-t</option></group>
<group choice="opt"><option>-u</option> <replaceable>
user</replaceable></group>
<group choice="opt"><option>--nonewdcop</option></group>

<group><arg choice="req"><replaceable>command</replaceable> <arg><replaceable>arg1</replaceable></arg>
	  <arg><replaceable>arg2</replaceable></arg>
          <arg rep="repeat"><replaceable></replaceable></arg></arg></group>
</cmdsynopsis>
<cmdsynopsis>
<command>kdesu</command>
<arg choice="opt">&kde; Generic Options</arg>
<arg choice="opt">Qt Generic Options</arg>
</cmdsynopsis>

<para>The command line options are explained below.</para>

<variablelist>
<varlistentry>
<term><option>-c <replaceable>program</replaceable></option></term>
<listitem><para>This specifies the program to run as root. It has to be passed
in one argument. So if, for example, you want to start a new file manager, you
would enter at the prompt: <userinput><command>kdesu <option>-c <replaceable>kfm
-sw</replaceable></option></command></userinput></para></listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option></term>
<listitem><para>Show debug information.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f <replaceable>file</replaceable></option></term>
<listitem><para>This option allow efficient use of &kdesu; in
<filename>.desktop</filename> files. It tells &kdesu; to examine the
file specified by <parameter>file</parameter>. If this file is
writable by the current user, &kdesu; will execute the command as the
current user. If it is not writable, the command is executed as user
<parameter>user</parameter> (defaults to root).</para>
<para><parameter>file</parameter> is evaluated like this: if
<parameter>FILE</parameter> starts with a <literal>/</literal>, it is
taken as an absolute filename. Otherwise, it is taken as the name of a
global &kde; configuration file. For example: to configure the K display
manager, <application>kdm</application>, you could issue
<command>kdesu <option>-c kdmconfig -f
kdmrc</option></command></para></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option> <replaceable>icon name</replaceable></term>
<listitem><para>Specify icon to use in the password dialog.  You may specify
just the name, without any extension.</para>
<para>For instance to run <command>kfmclient</command> and show the
&konqueror; icon in the password dialog:</para>
<screen><userinput><command>kdesu</command>  <option>-i konqueror</option> <command>kfmclient</command></userinput></screen>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-n</option></term>
<listitem><para>Do not keep the password. This disables the <guilabel>keep
password</guilabel> checkbox in the password dialog.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>priority</replaceable></term>
<listitem>
<para>Set priority value.  The priority is an arbitrary number between 0 and
100, where 100 means highest priority, and 0 means lowest.  The default is
50.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-r</option></term>
<listitem><para>Use realtime scheduling.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-s</option></term>
<listitem><para>Stop the kdesu daemon. See <xref
linkend="sec-password-keeping"/>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option></term>
<listitem><para>Enable terminal output. This disables password keeping. This is
largely for debugging purposes; if you want to run a console mode app, use the
standard <command>su</command> instead.</para> </listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option> <replaceable> user</replaceable></term>
<listitem><para>While the most common use for &kdesu; is to run a command as
the superuser, you can supply any user name and the appropriate
password.</para>
</listitem>
</varlistentry>

</variablelist>

</chapter>

<chapter id="Internals">
<title>Internals</title>

<sect1 id="x-authentication">
<title>X authentication</title>

<para>The program you execute will run under the root user id and will
generally have no authority to access your X display. &kdesu; gets
around this by adding an authentication cookie for your display to a
temporary <filename>.Xauthority</filename> file. After the command
exits, this file is removed. </para>

<para>If you don't use X cookies, you are on your own. &kdesu; will
detect this and will not add a cookie but you will have to make sure
that root is allowed to access to your display.</para>

</sect1>

<sect1 id="interface-to-su">
<title>Interface to <command>su</command></title>

<para>&kdesu; uses the sytem's <command>su</command> for acquiring
priviliges. In this section, I explain the details of how &kdesu; does
this. </para>

<para>Because some <command>su</command> implementations (&ie; the one
from &RedHat;) don't want to read the password from
<literal>stdin</literal>, &kdesu; creates a pty/tty pair and executes
<command>su</command> with it's standard filedescriptors connected to
the tty.</para>

<para>To execute the command the user selected, rather than an
interactive shell, &kdesu; uses the <option>-c</option> argument with
<command>su</command>. This argument is understood by every shell that
I know of so it should work portably. <command>su</command> passes
this <option>-c</option> argument to the target user's shell, and the
shell executes the program. Example command: <command>su <option>root
-c <replaceable>the_program</replaceable></option></command>.</para>

<para>Instead of executing the user command directly with
<command>su</command>, &kdesu; executes a little stub program called
<application>kdesu_stub</application>. This stub (running as the
target user), requests some information from &kdesu; over the pty/tty
channel (the stub's stdin and stdout) and then executes the user's
program. The information passed over is: the X display, an X
authentication cookie (if available), the <envar>PATH</envar> and the
command to run. The reason why a stub program is used is that the X
cookie is private information and therefore cannot be passed on the
command line.</para>

</sect1>

<sect1 id="password-checking">
<title>Password Checking</title>

<para>&kdesu; will check the password you entered and gives an error
message if it is not correct. The checking is done by executing a test
program: <filename>/bin/true</filename>. If this succeeds, the
password is assumed to be correct.</para>

</sect1>

<sect1 id="sec-password-keeping">
<title>Password Keeping</title>

<para>For your comfort, &kdesu; implements a <quote>keep
password</quote> feature. If you are interested in security, you
should read this paragraph.</para>

<para>Allowing &kdesu; to remember passwords opens up a (small)
security hole in your system. Obviously, &kdesu; does not allow
anybody but your user id to use the passwords, but, if done without
caution, this would lowers <systemitem
class="username">root</systemitem>'s security level to that of a
normal user (you). A hacker who breaks into your account, would get
<systemitem class="username">root</systemitem> access. &kdesu; tries
to prevent this. The security scheme it uses is, in my opinion at
least, reasonably safe and is explained here.</para>

<para>&kdesu; uses a daemon, called
<application>kdesud</application>. The daemon listens to a &UNIX;
socket in <filename>/tmp</filename> for commands. The mode of the
socket is 0600 so that only your user id can connect to it. If
password keeping is enabled, &kdesu; executes commands through this
daemon. It writes the command and <systemitem
class="username">root</systemitem>'s password to the socket and the
daemon executes the command using <command>su</command>, as describe
before. After this, the command and the password are not thrown
away. Instead, they are kept for a specified amount of time. This is
the timeout value from in the control module.  If another request for
the same command is coming within this time period, the client does
not have to supply the password. To keep hackers who broke into your
account from stealing passwords from the daemon (for example, by
attaching a debugger), the daemon is installed set-group-id
nogroup. This should prevent all normal users (including you) from
getting passwords from the <application>kdesud</application>
process. Also, the daemon sets the <envar>DISPLAY</envar> environment
variable to the value it had when it was started. The only thing a
hacker can do is execute an application on your display.</para>

<para>One weak spot in this scheme is that the programs you execute
are probably not written with security in mind (like setuid
<systemitem class="username">root</systemitem> programs). This means
that they might have buffer overruns or other problems and a hacker
could exploit those.</para>

<para>The use of the password keeping feature is a tradeoff between
security and comfort. I encourage you to think it over and decide for
yourself if you want to use it or not.</para>

</sect1>
</chapter>

<chapter id="Author">
<title>Author</title>

<para>&kdesu;</para>

<para>Copyright 2000 &Geert.Jansen;</para>

<para>&kdesu; is written by &Geert.Jansen;. It is somewhat based on
Pietro Iglio's &kdesu;, version 0.3. Pietro and I agreed that I will
maintain this program in the future.</para>

<para>The author can be reached through email at &Geert.Jansen.mail;.
Please report any bugs you find to me so that I can fix them. If you
have a suggestion, feel free to contact me.</para>

&underFDL;
&underArtisticLicense;

</chapter>

</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->