Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

3 files changed, 504 insertions, 0 deletions

diff --git a/doc/kdesu/Makefile.am b/doc/kdesu/Makefile.am
new file mode 100644
index 000000000..bafa3f6c3
--- /dev/null
+++ b/doc/kdesu/Makefile.am
@@ -0,0 +1,5 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+KDE_MANS = AUTO
+
diff --git a/doc/kdesu/index.docbook b/doc/kdesu/index.docbook
new file mode 100644
index 000000000..800d20b10
--- /dev/null
+++ b/doc/kdesu/index.docbook
@@ -0,0 +1,320 @@
+<?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:
+-->
+
diff --git a/doc/kdesu/man-kdesu.1.docbook b/doc/kdesu/man-kdesu.1.docbook
new file mode 100644
index 000000000..b9c5ac4ca
--- /dev/null
+++ b/doc/kdesu/man-kdesu.1.docbook
@@ -0,0 +1,179 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+<title>KDE User's Manual</title>
+<author>&Lauri.Watts; &Lauri.Watts.mail;</author>
+<date>Jun 7, 2005</date>
+<productname>K Desktop Environment</productname>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>kdesu</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>kdesu</command></refname>
+<refpurpose>Runs a program with elevated privileges</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<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>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para>&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 optionally remember passwords
+for you. If you are using this feature, you only need to enter the
+password once for each command.</para>
+
+<para>This program is meant to be started from the command line or
+from <filename>.desktop</filename> files.</para>
+</refsect1>
+
+<refsect1>
+<title>Options</title>
+
+<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>
+</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. This is the daemon that caches
+successful passwords in the background.  This feature may also be disabled with
+<option>-n</option> when &kdesu; is initially run.</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>
+
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+<para>su(1)</para>
+
+<para>More detailed user documentation is available from <ulink
+url="help:/kdesu">help:/kdesu</ulink>
+(either enter this <acronym>URL</acronym> into &konqueror;, or run
+<userinput><command>khelpcenter</command>
+<parameter>help:/kdesu</parameter></userinput>).</para>
+
+</refsect1>
+
+<refsect1>
+<title>Examples</title>
+<para>Run <command>kfmclient</command> as user <systemitem
+class="username">jim</systemitem>, and show the &konqueror; icon in the
+password dialog:</para>
+<screen><userinput><command>kdesu</command> <option>-u jim</option> <option>-i konqueror</option> <command>kfmclient</command></userinput></screen>
+
+</refsect1>
+
+<refsect1>
+<title>Authors</title>
+<para>&kdesu; was written by
+<personname><firstname>Geert</firstname><surname>Jansen</surname></personname> <email>jansen@kde.org</email>
+and <personname><firstname>Pietro</firstname><surname>Iglio</surname></personname>
+<email>iglio@fub.it</email>. 
+</para>
+</refsect1>
+
+</refentry>