add more spacing

[personal-kdebase.git] / runtime / doc / userguide / kde-for-admins.docbook

<part id="kde-for-administrators">
<partinfo>
<authorgroup>
<author>
<personname>
<firstname>Waldo</firstname>
<surname>Bastian</surname>
</personname>
<email>bastian@kde.org</email>
</author>
<othercredit role="reviewer">
&Philip.Rodrigues;
&Philip.Rodrigues.mail;
</othercredit>
</authorgroup>
</partinfo>

<title>&kde; for Administrators</title>

<chapter id="kde-internals">
<title>&kde; Internals</title>

<sect1 id="kde-for-admins-overview">
<title>Overview</title>
<para>to be written</para>
</sect1>

<sect1 id="directory-layout">
<title>Directory Layout</title>

<para>&kde; defines a filesystem hierarchy which is used by the &kde;
environment itself as well as all &kde; applications. In general &kde;
stores all its files in a directory tree with a fixed structure.
</para>

<para>By default &kde; uses two directory trees:</para>

<itemizedlist>
<listitem><para>One at the system level (for example <filename
class="directory">/opt/kde3</filename>).</para></listitem>
<listitem><para>One at the user level in the user's home directory
(usually <filename class="directory">
~/.kde</filename>)</para></listitem>
</itemizedlist>

<para>As a system administrator you can create additional trees. Such
additional trees can be used for <link
linkend="user-profiles">profiles</link></para>

<informalexample><para>&SuSE; &Linux; for example uses:</para>

<itemizedlist>
<listitem><para><filename
class="directory">$<envar>HOME</envar>/.kde</filename></para></listitem>
<listitem><para><filename
class="directory">/opt/kde3</filename>. (This is
&SuSE;-specific; other distributions may use
<filename class="directory">/usr</filename> or <filename
class="directory">/usr/kde3</filename>)</para></listitem>
<listitem><para><filename
class="directory">/etc/opt/kde3</filename>. (This was added by
&SuSE;).</para></listitem>
</itemizedlist>

<para>If you have the KIOSK Admin tool v0.7 or later installed you can
check which directory trees are used with the following command:
<userinput><command>kiosktool-kdedirs</command>
<option>--check</option></userinput></para>
</informalexample>

<para>&kde; and &kde; applications look up files by scanning all the
&kde; directory trees.  The directory trees are checked in order of
precedence. When a file is present in multiple directory trees, the
file from the last tree takes precedence.  Normally, the tree
located in the user's home directory has the highest precedence. This
is also the directory tree to which changes are written.</para>

<informalexample>
<para>For information about the <literal>text/plain</literal> &MIME; type
the following files are searched:</para>

<itemizedlist>
<listitem><para><filename
class="directory">$<envar>HOME</envar>/.kde/share/mimelnk/text/plain.desktop</filename></para></listitem>
<listitem><para><filename
class="directory">/opt/kde3/share/mimelnk/text/plain.desktop</filename></para></listitem>
<listitem><para><filename
class="directory">/etc/opt/kde3/share/mimelnk/text/plain.desktop</filename></para></listitem>
</itemizedlist>

<para>If a user makes a change, the change is written to <filename
class="directory">$<envar>HOME</envar>/.kde/share/mimelnk/text/plain.desktop</filename></para>
</informalexample>

<para>For configuration files the story is slightly different. If
there are multiple configuration files found in the directory trees
with the same name, their content is combined. The precedence order of
the directory trees plays a role here. When two files define the same
configuration key, the file with the highest precedence determines
which value is used for the key.</para>

<informalexample><para>
For example, if the following two files exist, with these contents:</para>
<variablelist>
<varlistentry><term><filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename></term>
<listitem><programlisting>
Color=red
Shape=circle
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term><filename>/etc/opt/kde3/share/config/foobar</filename></term>
<listitem><programlisting>
Color=blue
Position=10,10
</programlisting>
</listitem>
</varlistentry>
</variablelist>

<para>The files will be merged to result in:</para>

<programlisting>
Color=red
Shape=circle
Position=10,10
</programlisting>

</informalexample>
</sect1>

<sect1 id="specifying-directories">
<title>Specifying Directories</title>

<para>

<segmentedlist>
<segtitle>Environment Variable</segtitle>
<segtitle>Example Setting(s)</segtitle>
<segtitle>Comment</segtitle>

<seglistitem>
<seg><envar>KDEHOME</envar></seg>
<seg><filename class="directory">~/.kde</filename></seg>
<seg></seg>
</seglistitem>

<seglistitem>
<seg><envar>KDEROOTHOME</envar></seg>
<seg><filename class="directory">/root/.kde</filename></seg>
<seg>Different variable to prevent
root writing to $KDEHOME of the user after running
<command>su</command>.</seg>
</seglistitem>

<seglistitem>
<seg><envar>KDEDIR</envar></seg>
<seg><filename class="directory">/opt/kde3</filename>, <filename
class="directory">/usr</filename>, <filename
class="directory">/usr/kde3</filename></seg>
<seg>Vendor dependent. Used by &kde; 2. If not set, falls back to
compiled-in default.</seg>
</seglistitem>

<seglistitem>
<seg><envar>KDEDIRS</envar></seg>
<seg><filename class="directory">/opt/kde3</filename>, <filename
class="directory">/usr</filename>, <filename
class="directory">/usr/kde3</filename></seg>
<seg>New in &kde;3. Can list multiple locations separated by a
colon. If not set, falls back to $<envar>KDEDIR</envar></seg>
</seglistitem>

</segmentedlist>
</para>
<para>Don't <emphasis>need</emphasis> to be set, defaults work just fine.</para>
<para>Running &kde;2 next to &kde;3? Point $<envar>KDEDIR</envar> to
&kde; 2 and $<envar>KDEDIRS</envar> to &kde; 3.</para>

<informalexample>
<para>A staff member at a university could have the following
settings:</para>
<programlisting>
KDEHOME='~/.kde3'
KDEROOTHOME='/root/.kde3'
KDEDIRS='/opt/kde_staff:/opt/kde3'
</programlisting>

</informalexample>

</sect1>

<sect1 id="user-profiles">
<title>User Profiles</title>

<para>In the previous example <filename
class="directory">/opt/kde_staff</filename> contained additional settings
and applications for staff members. <quote>User Profiles</quote> allow you
to add this directory only for certain users and not for others.  Add the
following to <filename>/etc/kderc</filename>:</para>

<programlisting>
[Directories-staff]
prefixes=/opt/kde_staff
</programlisting>

<para>This creates a profile named <quote>staff</quote> that adds the
<filename class="directory">/opt/kde_staff</filename> directory
tree. (Note that &SuSE; &Linux; uses
<filename>/etc/kde3rc</filename> instead of
<filename>/etc/kderc</filename>. Now that we have a named profile it
can be assigned to users.</para>

<para>To map profiles to users a mapping file needs to be specified in
<filename>/etc/kderc</filename>:</para>

<programlisting>
[Directories]
userProfileMapFile=/etc/kde-user-profile
</programlisting>

<para>It is now possible to assign a profile based on either the user name
or based on the &UNIX; group the user is part of.</para> 

<para>To assign the staff profile to all users that are a member of the
&UNIX; group staff_members add the following to
<filename>/etc/kde-user-profile</filename>:</para>

<programlisting>
[General]
groups=staff_members
[Groups]
staff_members=staff
</programlisting>

<para>It is also possible to assign a profile to a single user:</para>

<programlisting>
[Users]
bastian=staff
</programlisting>

</sect1>

<sect1 id="directory-layout-revisited">
<title>Directory Layout Revisited</title>

<para>Each directory tree used by &kde; has a fixed directory structure.
Directories that are not relevant for a certain tree, or simply not used can
be left out though. For example, directories used for temporary files are
usually only found under <filename
class="directory">$<envar>KDEHOME</envar></filename> but not in any other
directory tree.</para>

</sect1>

<sect1 id="architecture-specific-directories">
<title>Architecture-specific Directories</title>

<para>Architecture (OS and CPU type) specific directories:</para>

<variablelist>
<varlistentry>
<term><filename class="directory">bin</filename></term>
<listitem><para>Used for &kde; executables.</para></listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">lib</filename></term>
<listitem><para>Used for &kde; libraries.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">lib/kde3</filename></term>
<listitem><para>This directory contains components, plugins, and other
runtime loadable objects for use by &kde; 3.<replaceable>x</replaceable>
applications.</para></listitem> 
</varlistentry>
</variablelist>

</sect1>

<sect1 id="shared-directories">
<title>Shared Directories</title>

<para>Shared: Not architecture specific, can be shared between different
archs.</para>

<variablelist>
<varlistentry>
<term><filename class="directory">share/applnk</filename></term>
<listitem><para><literal role="extension">.desktop</literal> files for
&kde;-menu (old)</para></listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/applications</filename></term>
<listitem><para><literal role="extension">.desktop</literal> files for
&kde;-menu (since &kde; 3.2)</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/apps</filename></term>
<listitem><para>Contains application-specific data files. Each
application has a sub-directory here for storing additional data
files.</para></listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/config</filename></term>
<listitem><para>Configuration files. Configuration files are normally
named after the application they belong to plus the letters
<quote>rc</quote>. A special case is <filename>kdeglobals</filename>. 
This file is read by all &kde; applications.</para></listitem>
</varlistentry>

<varlistentry>
<term><filename
class="directory">share/config/session</filename></term>
<listitem><para>This directory is used by session management and is
normally only available under <filename
class="directory">$<envar>KDEHOME</envar></filename>. At the end of a
session &kde; applications store their state here. The file names
consist of the name of the application followed by a number. The
session manager <command>ksmserver</command> stores references to
these numbers when saving a session in
<filename>ksmserverrc</filename>.</para></listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/doc/HTML</filename></term>
<listitem><para>This directory contains documentation for &kde;
applications. Documentation is categorized by language and the
application it belongs to. Normally at least two files can be found in
a directory: <filename>index.docbook</filename>, which contains the
documentation in the unformatted DocBook format, and
<filename>index.cache.bz2</filename>, which contains the same
documentation formatted as <command>bzip2</command>-compressed
&HTML;. The &HTML; version is used by &khelpcenter;. If the &HTML;
version is missing, &khelpcenter; will regenerate it from the DocBook
version but this is a time-consuming process.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/icons</filename></term>
<listitem><para>Under this directory icons are stored. Icons are
categorized by theme, dimension and usage category.</para></listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/mimelnk</filename></term>
<listitem><para>In this directory,<literal
role="extension">.desktop</literal> files that describe &MIME; types
are stored. &kde; uses &MIME; types to identify the type of a
file.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/services</filename></term>
<listitem><para>This directory contains <literal
role="extension">.desktop</literal> files that describe services. Services
are like applications but are usually launched by other applications instead
of the user. Services do not appear in the &kde; menu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/servicetypes</filename></term>
<listitem><para>This directory contains <literal
role="extension">.desktop</literal> files that describe
servicetypes. A servicetype usually represents a certain programming
interface. Applications and Services include in their <literal
role="extension">>.desktop</literal> files the servicetypes that they
provide.</para> </listitem></varlistentry>

<varlistentry>
<term><filename class="directory">share/sounds</filename></term>
<listitem><para>This directory contains sound files.</para></listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/templates</filename></term>
<listitem><para>This directory contains templates for creating files
of various types. A template consists of a <literal
role="extension">.desktop</literal> file that describes the file and
that includes a reference to a file in the <filename
class="directory">.source</filename> sub-directory. The templates in
this directory appear in the <guimenu>Create New</guimenu> menu
available on the desktop and in the file browser. When a user selects
a template from the menu its source file is copied.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">share/wallpapers</filename></term>
<listitem><para>This directory contains images that can be used as
background picture</para></listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="host-specific-directories">
<title>Host-specific Directories</title> 

<para>There are three host-specific directories that are usually
symlinked to other locations. If the directories do not already exist,
the following symlinks and directories will be created using the
<command>lnusertemp</command> utility:</para>

<variablelist>

<varlistentry>
<term><filename>$<envar>KDEHOME</envar>/socket-$<envar>HOSTNAME</envar></filename></term>
<listitem><para>Usually <filename
class="directory">/tmp/ksocket-$<envar>USER</envar>/</filename>, this
is used for various &UNIX; sockets.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename>$<envar>KDEHOME</envar>/tmp-$<envar>HOSTNAME</envar></filename></term>
<listitem><para>Usually <filename
class="directory">/tmp/kde-$<envar>USER</envar>/</filename>, this is used for temporary files.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename>$<envar>KDEHOME</envar>/cache-$<envar>HOSTNAME</envar></filename></term>
<listitem><para>Usually <filename
class="directory">/var/tmp/kdecache-$<envar>USER</envar>/</filename>,
this is used for cached files.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Since both <filename class="directory">/tmp</filename> and
<filename class="directory">/var/tmp</filename> are world writable,
there is a possibility that one of the above directories already
exists but is owned by another user. In that case the
<command>lnusertemp</command> utility will create a new directory with
an alternative name and link to that instead.</para>

</sect1>

<sect1 id="configuration-files">
<title>Configuration Files</title> <para>&kde; uses a simple
text-based file format for all its configuration files. It consists of
key-value pairs that are placed in groups.  All &kde; configuration
files use <acronym>UTF</acronym>-8 encoding for text outside the
<acronym>ASCII</acronym> range.</para>

<para>The start of a group is indicated by a group name that is placed
in square brackets. All the key-value entries that follow belong to
the group. The group ends when either another group starts or when the
end of the file is reached. Entries at the top of the
file that are not preceded by a group name belong to the default
group.</para>

<informalexample><para>The following example shows a configuration
file that consists of two groups. The first group contains the keys
<varname>LargeCursor</varname> and <varname>SingleClick</varname>, the
second group contains the keys <varname>Show hidden files</varname>
and <varname>Sort by</varname>:</para>

<programlisting>
[KDE]
LargeCursor=false
SingleClick=true
</programlisting>

<programlisting>
[KFileDialog Settings]
Show hidden files=false
Sort by=Name
</programlisting>
</informalexample>

<para>Entries in a group consist of a key and value separated by an equals
sign. The key can contain spaces and may be followed by options placed in
square brackets.  The part after the equals sign is the value of the
entry. Any white space surrounding the equals sign is ignored, as is any
trailing white space. Put more concisely, the format is:</para>

<programlisting>
<replaceable>entry</replaceable>=<replaceable>value</replaceable>
</programlisting>

<para>If a value is supposed to include a space at the begin or end
then this can be achieved by using a backslash followed by an
<quote>s</quote>.</para>

<para>There are several other backslash codes; here is a complete
list:
<itemizedlist>
<listitem><para><token>\s</token> can be used as space</para>
</listitem>
<listitem><para><token>\t</token> can be used to include a tab</para>
</listitem>
<listitem><para><token>\r</token> for a carriage return character</para>
</listitem>
<listitem><para><token>\n</token> for a linefeed character (new line)</para>
</listitem>
<listitem><para><token>\\</token> to include the backslash itself</para>
</listitem>
</itemizedlist></para>

<informalexample><para>In the following example the value of the
<varname>Caption</varname> entry starts with two spaces while the
<varname>Description</varname> entry contains three lines of
text. Linefeeds in backslash notation are used to separate the
different lines.</para>

<programlisting>
[Preview Image]
Caption=\s My Caption
Description=This is\na very long\ndescription.
</programlisting>
</informalexample>

<para>Empty lines in configuration files are ignored, as are lines that
start with a hash mark (<quote>#</quote>). The hash mark can be used to add
comments to configuration files. It should be noted that when a &kde;
application updates a configuration file the comments are
<emphasis>not</emphasis> preserved.</para>

<para>There can be multiple configuration files with the same name in the
<filename class="directory">share/config</filename> sub-directory of the
various &kde; directory trees. In this case the information of all these
configuration files is combined on a key-by-key basis.  If the same key
within a certain group is defined in more than one place, the key value read
from the directory tree with the highest precedence will be used.
Configuration files under <filename
class="directory">$<envar>KDEHOME</envar></filename> always have the highest
precedence.  If a key in a certain group is defined multiple times in a
single file, the value of the last entry is used.</para>

<informalexample>
<para>If <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename>
contains:
<programlisting>
[MyGroup]
Color=red
Shape=circle
</programlisting>
and <filename>/etc/opt/kde3/share/config/foobar</filename> contains
<programlisting>
[MyGroup]
Color=blue
Position=10,10
</programlisting>
the result will be:
<programlisting>
[MyGroup]
Color=red
Shape=circle
Position=10,10
</programlisting>
</para>
</informalexample>

<informalexample>
<para>If
        <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename>
        contains
<programlisting>
[MyGroup]
Color=red
Shape=circle
[MyGroup]
Color=green
</programlisting>
and <filename>/opt/kde_staff/share/config/foobar</filename> contains
<programlisting>
[MyGroup]
Color=purple
Position=20,20
</programlisting>
and <filename>/etc/opt/kde3/share/config/foobar</filename> contains
<programlisting>
[MyGroup]
Color=blue
Position=10,10
</programlisting>
the result will be:
<programlisting>
[MyGroup]
Color=green
Shape=circle
Position=20,20
</programlisting>
</para>
</informalexample>

<para>To prevent users being able to override default settings,
settings can be marked immutable. Settings can be made immutable
individually, per group or per file. An individual entry can be locked
down by adding <userinput>[$i]</userinput> behind the key, &eg;:
<programlisting>
Color[$i]=blue
</programlisting>
</para>
<para>A group of entries can be locked down by placing
<userinput>[$i]</userinput> behind the group name, &eg;:
<programlisting>
[MyGroup][$i]
</programlisting>
</para>
<para>To lock down the entire file, start the file with
<userinput>[$i]</userinput> on a single line, &ie;:
<programlisting>
[$i]
</programlisting>
</para>

<informalexample>
<para>If
        <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename>
        contains:
<programlisting>
[MyGroup]
Color=red
Shape=circle
</programlisting>
and <filename>/etc/opt/kde3/share/config/foobar</filename> contains:
<programlisting>
[MyGroup][$i]
Color=blue
Position=10,10
</programlisting>
the result will be:
<programlisting>
[MyGroup]
Color=blue
Position=10,10
</programlisting>
</para>
</informalexample>

<informalexample><para>If
        <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename>
        contains:
<programlisting>
[MyGroup]
Color=red
Shape=circle
</programlisting>
and <filename>/opt/kde_staff/share/config/foobar</filename> contains
<programlisting>
[MyGroup]
Color=purple
Shape=rectangle
</programlisting>
and <filename>/etc/opt/kde3/share/config/foobar</filename> contains
<programlisting>
[MyGroup][$i]
Color=blue
Position=10,10
</programlisting>
the result will be
<programlisting>
[MyGroup]
Color=purple
Shape=rectangle
Position=10,10
</programlisting>
</para>
</informalexample>


<para>So-called <quote>Shell Expansion</quote> can be used to provide more
dynamic default values. With shell expansion the value of a configuration
key can be constructed from the value of an environment variable or from the
output of a shell command.  To enable shell expansion for a configuration
entry, the key must be followed by <token>[$e]</token>.  Normally the
expanded form is written into the user's configuration file after first use.
To prevent that, it is recommend to lock the configuration entry down by
using <token>[$ie]</token>.  The user can't change it then of course.</para>

<informalexample>
<para>In the following example the value for the <varname>Host</varname>
entry is determined by the output of the <command>hostname</command>
program. This setting is also locked down to ensure that the value is always
determined dynamically.</para>

<para>The value for the <varname>Email</varname> entry is determined by
filling in the values of the $<envar>USER</envar> and $<envar>HOST</envar>
environment variables. When <systemitem class="username">joe</systemitem> is
logged in on <systemitem class="systemname">joes_host</systemitem> this will
result in a value equal to <literal>joe@joes_host</literal>. The setting is
not locked down.</para>

<programlisting>
[Mail Settings] 
Host[$ie]=$(hostname)
Email[$e]=${USER}@${HOST}
</programlisting>
</informalexample>

<para>Most configuration entries can be indexed with a language code. In
this case, the language that the user has selected for use on the desktop is
used to look up the key value. If the default language (American English)
has been selected or if there is no index that corresponds to the selected
language, the key entry without index is used.</para>

<informalexample>
<para>In the following example the value of the <varname>Caption</varname>
entry depends on the language. If the user has selected French as language
(language code <literal>fr</literal>) the value of the entry will be
<quote>Ma L&eacute;gende</quote>. In all other cases the value <quote>My
Caption</quote> will be used.</para>

<programlisting>
[Preview Image]
Caption=My Caption
Caption[fr]=Ma L&eacute;gende
</programlisting>
</informalexample>

<informalexample>
<para>In this example the value of the <varname>Caption</varname> entry
depends on the language. If the user has selected French as language
(language code <literal>fr</literal>) the value of the entry will be
<quote>Ma L&eacute;gende.</quote> In all other cases the value <quote>My
Caption</quote> will be used.</para>

<programlisting>
[Preview Image]
Caption=My Caption
Caption[fr]=Ma L&eacute;gende
</programlisting>
</informalexample>

<para>In general the entries that can appear in a configuration file are not
documented.  With &kde; 3.2 a start has been made to change this. In
<filename
class="directory">$<envar>KDEDIR</envar>/share/config.kcfg</filename>, files
can be found that provide a formal description of the possible entries in a
configuration file. These are used by the new &kde; Configuration Editor
when available.</para>

<informalexample>
<para>Here is an example &XML; configuration file:
<programlisting>
<markup>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd"&gt;
&lt;kcfg&gt;
    &lt;kcfgfile name="korganizerrc"/&gt;
    &lt;group name="General"&gt;
         &lt;entry type="Bool" key="Auto Save"&gt;
             &lt;label&gt;Enable automatic saving of calendar&lt;/label&gt;
             &lt;default&gt;true&lt;/default&gt;
         &lt;/entry&gt;
         &lt;entry type="Int" key="Auto Save Interval"&gt;
             &lt;default&gt;10&lt;/default&gt;
         &lt;/entry&gt;
    &lt;/group&gt;
&lt;/kcfg&gt;
</markup>
</programlisting>
</para>
<para>It has the same effect as:
<programlisting>
[General]
Auto Save=false
Auto Save Interval=25
</programlisting>
</para>
</informalexample>

</sect1>

<sect1 id="kde-startup-sequence">
<title>&kde; Startup Sequence</title>

<sect2 id="kdm">
<title>&kdm;</title>

<para>Always runs as <systemitem class="username">root</systemitem>! Uses
<filename>$<envar>KDEDIR</envar>/share/config/kdmrc</filename> and
<filename>/etc/X11/xdm/Xservers</filename>. The latter contains entries
like:</para>

<programlisting>
:0 local /usr/X11R6/bin/X :0 vt07
</programlisting>

<para>Relevant startup files are also: </para>
<simplelist>
<member>
[X-*-Core] section in <filename>kdmrc</filename>
</member>
<member>
Setup - <filename>/etc/X11/xdm/Xsetup</filename>
</member>
<member>
User enters username &amp; password
</member>
<member>
Startup - <filename>/etc/X11/xdm/Xstartup</filename> - prepare as root
</member>
<member>
Session - <filename>/etc/X11/xdm/Xsession</filename> - starts session as user
</member>
<member>
= For a KDE session: <command>kde</command> or <command>startkde</command>
</member>
<member>
= If present <filename>~/.xsession</filename> or <filename>~/.xinitrc</filename>
</member>
<member>
Reset - <filename>/etc/X11/xdm/Xreset</filename> - after session finished
</member>
</simplelist>

</sect2>

<sect2 id="startkde">
<title>The &kde; Startup Script: <command>startkde</command></title>

<para>The &kde; startup sequence starts with the
<filename>startkde</filename> script. In most cases this script gets called
from the display manager (&kdm;) once the user has been authenticated. Their
are two very important lines in the <filename>startkde</filename>
script:</para>

<programlisting>
LD_BIND_NOW=true kdeinit4 +kcminit_startup and kwrapper4 ksmserver $KDEWM
</programlisting>

<para>The first line starts the <command>kdeinit4</command> master process.
The <command>kdeinit4</command> master process is used to start all other
&kde; processes.  It show up in the output of <command>ps
<option>aux</option></command> as <computeroutput>kdeinit4:
Running...</computeroutput>. The arguments after <command>kdeinit4</command>
are the names of additional processes to be started.  The <token>+</token>
indicates that <command>kdeinit4</command> needs to wait till the process has
finished.  <command>kdeinit4</command> also starts
<command>klauncher</command> and <command>kded</command>.</para>

<para>The second of the two lines asks <command>kdeinit4</command> to start
the <command>ksmserver</command> session manager process.  The session
manager determines the lifetime of the session. When this process exits, the
user is logged out.</para>

</sect2>
</sect1>

<sect1 id="background-processes">
<title>Background Processes</title>

<para>All &kde; background services are user-specific: unlike system daemons
they are not shared between users. As well as being unique per user they are
also unique per X-server display. The processes are:</para>

<variablelist>
<varlistentry>
<term><command>dcopserver</command></term>
<listitem><para>Desktop communication</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>kded</command></term>
<listitem><para>Generic service daemon.</para>
<para>Triggers <link linkend="ksycoca">Sycoca</link> database updates when
needed</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>kcminit</command></term>
<listitem><para>Initialization service</para>
<para>See <xref linkend="kcminit"/> for more information.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>klauncher</command></term>
<listitem><para>Program launch (this is <emphasis>not</emphasis> the
<keycombo action="simul">&Alt;<keycap>F2</keycap>
</keycombo>dialog!)</para>
<para>See <xref linkend="klauncher"/> for more information.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>knotify</command></term>
<listitem><para>User notifications.</para>
<para>See <xref linkend="knotify"/> for more information.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>ksmserver</command></term>
<listitem><para>Session management</para>
<para>See <xref linkend="ksmserver"/> for more information.</para>
</listitem>
</varlistentry>

</variablelist>

<sect2 id="kdeinit">
<title><command>kdeinit</command></title>
<para><command>kdeinit</command> is used to start all other &kde;
programs. <command>kdeinit</command> can start normal binary program files
as well as <command>kdeinit</command> loadable modules
(<acronym>KLM</acronym>s).  <acronym>KLM</acronym>s work just like binary
program files but can be started more efficiently.  <acronym>KLM</acronym>s
live in <filename
class="directory">$<envar>KDEDIR</envar>/lib/kde3</filename></para>

<para>The drawback is that programs started this way appear as
<computeroutput><command>kdeinit</command></computeroutput> in the output of
<command>top</command> and <command>ps</command>. Use <command>top
<option>-c</option></command> or <command>ps <option>aux</option></command>
to see the actual program name:</para>

<screen>
<prompt>%</prompt><userinput><command>ps <option>aux</option></command></userinput>
<computeroutput>
waba     23184  0.2  2.1 23428 11124 ?  S    21:41   0:00 kdeinit4: Running...
waba     23189  0.2  2.4 25136 12496 ?  S    21:41   0:00 kdeinit4: klauncher
waba     23192  0.7  2.8 25596 14772 ?  S    21:41   0:00 kdeinit4: kded
waba     23203  0.8  3.4 31516 17892 ?  S    21:41   0:00 kdeinit4: knotify
</computeroutput>
</screen>

<para><computeroutput>kdeinit: Running...</computeroutput> indicates the
master <command>kdeinit</command> process. The other processes listed are
programs started as <acronym>KLM</acronym>s.</para>

<para>When <command>kdeinit</command> starts for the first time it will
launch <command>klauncher</command>, and
<command>kded</command>, as well as any additional programs specified on its
command line in the <command>startkde</command> script, normally
<command>kcminit_startup</command>.</para>

</sect2>

<sect2 id="kcminit">
<title>kcminit</title>

<para><command>kcminit</command> executes initialization services during
startup. Initialization services are specified in the .desktop files of
applications or services via the <varname>X-KDE-Init</varname> line:</para>

<programlisting>
[Desktop Entry]
Encoding=UTF-8
Exec=kcmshell4 energy
Icon=energy_star
Type=Application
X-KDE-Library=energy
X-KDE-Init=energy
</programlisting>

<para>Initialization services are typically used for initializing
hardware based on user-specified settings.</para>

<para><userinput><command>kcminit
<option>--list</option></command></userinput> can be used to show all
initialization services and <userinput><command>kcminit
<replaceable>service</replaceable></command></userinput> can be used to
execute a single service explicitly. This can be useful when investigating
startup problems.</para>

</sect2>

<sect2 id="klauncher">
<title><command>klauncher</command></title>

<para><command>klauncher</command> is a daemon which is responsible for
service activation within &kde;. It operates in close connection with the
<command>kdeinit</command> master process to start new processes. &kde;
applications communicate with <command>klauncher</command> over &DCOP; in
order to start new applications or services.</para>

<para>Best known from the error message: <computeroutput><errortext>
KLauncher could not be reached via DBus </errortext></computeroutput> which
either indicates a serious problem with the <command>dcopserver</command> or
that <command>klauncher</command> crashed.</para>

<para><command>klauncher</command> can be restarted by restarting
<command>kdeinit</command> from a console window. Make sure that
$<envar>HOME</envar>, $<envar>DISPLAY</envar> and the various
$<envar>KDEDIR(S)</envar> are set correctly when doing so!</para>

</sect2>

<sect2 id="knotify">
<title><command>knotify</command></title>

<para>The primary task of <command>knotify</command> is to relay sound
notifications to the sound server, it also provides alternative notification
methods.</para>

</sect2>


</sect1>

<sect1 id="ksmserver">
<title>KSMServer</title>

<para><command>ksmserver</command> is &kde;'s session manager. On startup
the session manager launches auto-start applications and restores
applications from the previous session.  The applications to auto-start are
indicated by <literal role="extension">.desktop</literal> files in the
<filename
class="directory">$<envar>KDEDIR</envar>/share/autostart</filename>
directory.  Whether or not to auto-start an application can be made
conditional upon some configuration entry determined by the
<varname>X-KDE-autostart-condition</varname> entry in the <literal
role="extension">.desktop</literal> file.</para>

<informalexample>
<para>The <filename>ktip.desktop</filename> file for example
contains:</para>

<programlisting>
X-KDE-autostart-condition=ktiprc:TipOfDay:RunOnStart:true
</programlisting>

<para>This means that the <filename>ktiprc</filename> configuration
file is checked for a <varname>RunOnStart</varname> entry in the
<varname>[TipOfDay]</varname> section. If no such entry is found,
<literal>true</literal> is assumed, which means that
<application>ktip</application> is one of the applications that is
auto-started by default.</para>
</informalexample>

<para>Some of the applications auto-started by <command>ksmserver</command>
are:</para>

<variablelist>

<varlistentry>
<term><command>kdesktop</command></term>
<listitem><para>The &kde; desktop</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>&kicker;</command></term>
<listitem><para>The &kde; panel</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>ktip</command></term>
<listitem><para>A tip of the day program</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>kwrited</command></term>
<listitem><para>A utility to receive system messages sent to the user</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&klipper;</term>
<listitem><para>A clipboard utility that docks in the panel</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>kalarm</command></term>
<listitem><para>A utility that warns about upcoming events and appointments</para>
</listitem>

</varlistentry>
</variablelist>

<para><command>kdesktop</command> in its turn automatically starts
applications stored in <filename
class="directory">$<envar>KDEHOME</envar>/Autostart</filename>. <command>kdesktop</command>
will automatically open any files stored in this directory including
documents, binary files or applications in the form of <literal
role="extension">.desktop</literal> files.</para>

<para>The &kde; session manager also restores one of the previous
sessions. A session contains a collection of applications as well as
application-specific information that reflects the state of the applications
at the time the session was saved.  Sessions are stored in the
<filename>ksmserverrc</filename> configuration file which contains
references to application-specific state information. The
application-specific state information is saved in <filename
class="directory">$<envar>KDEHOME</envar>/share/config/session</filename>.
The state information of &kwin; contains the location of the application
windows of all the other applications in the session.
</para>

</sect1>

<sect1 id="environment-variables">
<title>Environment variables</title>

<para>Some important environment variables used by &kde;:</para>

<variablelist>

<varlistentry>
<term>$<envar>KDEDIR</envar></term>
<listitem><para>Has to be set if
<envar>KDEDIRS</envar> is not set and has to point to the root of the
&kde; installation tree. Allows &kde; to find its data like icons,
menus and libraries.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDEDIRS</envar></term>
<listitem><para>Overrides <envar>KDEDIR</envar> and allows you to specify
multiple directories where &kde; searches for its data. Useful if you want
or have to install some programs to a different prefix than the rest of
&kde;.</para> 
</listitem>
</varlistentry>

<varlistentry><term><envar>$KDEHOME</envar></term><listitem><para>If
not set, &kde; uses <filename class="directory">~/.kde</filename> as
the directory where personal data is stored.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDEROOTHOME</envar></term><listitem><para>If
not set, &kde; uses <filename class="directory">~root/.kde</filename>
as the directory for <systemitem class="username">root</systemitem>'s
personal data. Was introduced to prevent &kde; from accidently
overwriting user data with root permissions when the user runs a &kde;
program after switching with <command>su</command> to <systemitem
class="username">root</systemitem>.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDEWM</envar></term><listitem><para>If the
<envar>KDEWM</envar> environment variable has been set, then it will
be used as &kde;'s window manager within the
<command>startkde</command> script instead of &kwin;.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_LANG</envar></term><listitem><para>Overrides
the &kde; language configuration, &eg; <userinput>KDE_LANG=fr kprogram
&amp;</userinput> starts a program with French translation if the
necessary files are installed.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_MULTIHEAD</envar></term><listitem><para>Set
this variable to <literal>true</literal> to indicate that &kde; is running
on a multi-head system.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_FORK_SLAVES</envar></term>
<listitem><para>(Since &kde; 3.2.3) Set this variable to spawn
<acronym>KIO</acronym>-slaves directly from the application process
itself. By default <acronym>KIO</acronym>-slaves are spawned using
<command>klauncher</command>/<command>kdeinit</command>. This option is
useful if the <acronym>KIO</acronym>-slave should run in the same
environment as the application. This can be the case with
<application>Clearcase</application>.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_HOME_READONLY</envar></term>
<listitem><para>Set this variable to indicate that your home directory is
mounted as read-only.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_NO_IPV6</envar></term><listitem><para>
(Since &kde; 3.2.3) - Set this variable to disable <acronym>IPv6</acronym>
support and <acronym>IPv6</acronym> <acronym>DNS</acronym>
lookups.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_IS_PRELINKED</envar></term><listitem><para>
(Since &kde; 3.2) - Set this variable to indicate that you have prelinked
your &kde; binaries and libraries. This will turn off
<command>kdeinit</command>.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_UTF8_FILENAMES</envar></term><listitem><para>If
this environment variable is set, &kde; assumes all filenames are in
<acronym>UTF-8</acronym> encoding regardless of the current C
locale.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDE_FULL_SESSION</envar></term><listitem><para>
(Since &kde; 3.2)  Automatically set to true by &kde; startup, it is used
by &eg; &konqueror; to know if it should consider remaining in memory
for future re-use when being closed. If not set, &konqueror; will exit
after being closed (&eg; &kdesu; does that, it's also useful for
debugging).</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDESYCOCA</envar></term><listitem><para>Allows
you to specify the path and the name of the generated &kde; system
configuration cache file.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDETMP</envar></term><listitem><para>Allows
to specify another path than <filename
class="directory">/tmp</filename> where &kde; stores its temporary
files.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>KDEVARTMP</envar></term><listitem><para>Allows
to specify another path than <filename
class="directory">/var/tmp</filename> where &kde; stores its variable
files.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>XDG_DATA_HOME</envar></term><listitem><para>
(Since &kde; 3.2) Defines the base directory relative to which user-specific
data files should be stored. Default is <filename
class="directory">$<envar>HOME</envar>/.local/share</filename></para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>XDG_DATA_DIRS</envar></term><listitem><para>
(Since &kde; 3.2) Defines the preference-ordered set of base directories to
search for data files in addition to the <filename
class="directory">$<envar>XDG_DATA_HOME</envar></filename> base
directory. Default is
<literal>/usr/local/share/:/usr/share/</literal></para>

<para>&kde; adds locations from $<envar>KDEDIRS</envar> and profiles
as well.  Used for <literal role="extension">.desktop</literal> and
<literal role="extension">.directory</literal> menu files. <literal
role="extension">.desktop</literal> files under <filename
class="directory">$<envar>XDG_DATA_DIRS</envar>/applications</filename>. 
<literal
role="extension">.directory</literal> files under
$XDG_DATA_DIRS/desktop-directories
</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>XDG_CONFIG_HOME</envar></term><listitem><para>
(&kde; 3.2) - Defines the base directory relative to which user
specific configuration files should be stored. Default is
<filename class="directory">$<envar>HOME</envar>/.config</filename>.</para>
</listitem>
</varlistentry>

<varlistentry><term>$<envar>XDG_CONFIG_DIRS</envar></term><listitem><para>
(&kde; 3.2) - Defines the preference-ordered set of base directories
to search for configuration files in addition to the $<envar>XDG_CONFIG_HOME</envar>
base directory. The default is <filename class="directory">/etc/xdg</filename> &kde; adds locations from
$<envar>KDEDIRS</envar> and profiles as well. Used by <literal role="extension">.menu</literal> descriptions in
<filename class="directory">$<envar>XDG_CONFIG_DIRS</envar>/menus</filename>.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="the-kdeinit-mystery">
<title>The kdeinit Mystery</title>

<!-- FIXME: Add more words. Fix markup -->

<para><command>kdeinit</command> is used to start all other &kde;
programs. <command>kdeinit</command> can start normal binary program f iles
as well as <command>kdeinit</command> loadable modules
(<acronym>KLM</acronym>s).  <acronym>KLM</acronym>s work just like binary
program files but can be started more efficiently.  <acronym>KLM</acronym>s
live in <filename
class="directory">$<envar>KDEDIR</envar>/lib/kde3</filename></para>

<para>The drawback is that programs started this way appear as
<computeroutput><command>kdeinit</command></computeroutput> in the
output of <command>top</command> and <command>ps</command>. Use
<command>top <option>-c</option></command> or <command>ps
<option>aux</option></command> to see the actual program name:</para>

<screen>
<prompt>%</prompt> <userinput><command>ps aux | grep bastian</command></userinput>
<computeroutput>
bastian  26061  0.0  2.2 24284 11492 ?       S    21:27   0:00 kdeinit: Running...
bastian  26064  0.0  2.2 24036 11524 ?       S    21:27   0:00 kdeinit: dcopserver
bastian  26066  0.1  2.5 26056 12988 ?       S    21:27   0:00 kdeinit: klauncher
bastian  26069  0.4  3.2 27356 16744 ?       S    21:27   0:00 kdeinit: kded
bastian  26161  0.2  2.7 25344 14096 ?       S    21:27   0:00 kdeinit: ksmserver
bastian  26179  1.1  3.4 29716 17812 ?       S    21:27   0:00 kdeinit: kicker
bastian  26192  0.4  3.0 26776 15452 ?       S    21:27   0:00 kdeinit: klipper
bastian  26195  1.0  3.5 29200 18368 ?       S    21:27   0:00 kdeinit: kdesktop
</computeroutput>
</screen>
<para>As you might have noticed, this has another side effect, making it
difficult to kill a process that is causing trouble:</para>

<screen><prompt>%</prompt> <userinput><command>killall kdesktop</command></userinput>
<computeroutput>kdesktop: no process killed</computeroutput></screen>

<para>You might be tempted to try <userinput><command>killall
kdeinit</command></userinput>, but killing all kdeinit processes will have
the effect of shutting down all of &kde;. In effect, total
destruction!</para>

<para>There are two simple solutions to this:</para>

<screen><prompt>%</prompt> <userinput><command>kdekillall kdesktop</command></userinput>
or good old
<prompt>%</prompt> <userinput><command>kill 26195</command></userinput></screen>
<para><command>kdekillall</command> is part of the &kde; <acronym>SDK</acronym>
package.</para>

</sect1>

</chapter>

<chapter id="customizing-kde">
<title>Customizing &kde;</title>


<sect1 id="desktop-icons">
<title>Desktop Icons</title>

<para>&kde; uses several types of icons:</para>
<itemizedlist>
<listitem><para>Documents</para>
</listitem>
<listitem><para>Links to Websites (using <literal role="extension">.desktop</literal> file)</para>
</listitem>
<listitem><para>Links to Applications (using <literal role="extension">.desktop</literal> file)</para>
</listitem>
<listitem><para>Devices - Disks, Partitions &amp; Peripherals:
<itemizedlist>
<listitem><para>Explicit using <literal role="extension">.desktop</literal> file</para>
</listitem>
<listitem><para>Automatic via devices:// io-slave</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem><para>Vendor-specific (&eg; &SuSE;'s My Computer)</para>
</listitem>
</itemizedlist>

<sect2 id="desktop-icons-websites">
<title>Websites</title>
<para>
Links to Websites using <literal role="extension">.desktop</literal>
file: <menuchoice><guimenu>Create
New</guimenu><guisubmenu>File</guisubmenu><guimenuitem>Link to
Location (URL)</guimenuitem></menuchoice>. Change Icon using
<guilabel>Properties</guilabel> dialogs.  The resulting <literal
role="extension">.desktop</literal> file:
<programlisting>
[Desktop Entry]
Encoding=UTF-8
Icon=/opt/kde3/share/apps/kdesktop/pics/ksslogo.png
Type=Link
URL=http://www.kde.org/
</programlisting>
</para>
</sect2>

<sect2 id="desktop-icons-applications">
<title>Applications</title>

<para>Links to Applications using <literal
role="extension">.desktop</literal> file: <menuchoice><guimenu>Create
New</guimenu><guisubmenu>File</guisubmenu><guimenuitem>Link to
Application</guimenuitem></menuchoice>. You must provide details
yourself. Drag from &kde; Menu: Either copy or link (creates symlink),
much easier</para>

<!-- Perhaps legacy and translated should be the other way around, but -->
<!-- this is how it appears in Waldo's presentation. Need to check -->
<!-- this -->

<programlisting>
[Desktop Entry]<co id="boilerplate"/>
Encoding=UTF-8
GenericName=IRC Client<co id="generic-desc"/>
GenericName[af]=Irc Kli&euml;t
GenericName[de]=IRC Programm
...
GenericName[zu]=Umthengi we IRC<co id="legacy"/>
SwallowExec=<co id="translated"/>
Name=KSirc
Name[af]=Ksirc
Name[de]=KSirc
...
</programlisting>

<calloutlist>
<callout arearefs="boilerplate"><para>Boiler plate</para>
</callout>
<callout arearefs="generic-desc"><para>Translated generic description, not used on desktop</para>
</callout>
<callout arearefs="legacy"><para>Legacy, can be removed</para>
</callout>
<callout arearefs="translated"><para>Translated name as it appears on desktop</para>
</callout>
</calloutlist>

<para>Desktop Icons</para>
<programlisting>
...
Name[zu]=Ksirc
MimeType=<co id="co-mimetype"/>
Exec=ksirc %i %m<co id="co-exec"/>
Icon=ksirc<co id="co-icon"/>
TerminalOptions=<co id="co-terminaloptions"/>
Path=<co id="co-path"/>
Type=Application<co id="co-type"/>
Terminal=0<co id="co-terminal"/>
X-KDE-StartupNotify=true<co id="co-x-kde-startupnotify"/>
X-DCOP-ServiceType=Multi<co id="co-x-dcop-servicetype"/>
Categories=Qt;KDE;Network<co id="co-categories"/>
</programlisting>

<calloutlist>
<callout arearefs="co-mimetype"><para>Supported &MIME; types, not used on
desktop</para>
</callout>
<callout arearefs="co-exec"><para>The command line to execute</para>
</callout>
<callout arearefs="co-icon"><para>The icon, from icon theme or full path</para>
</callout>
<callout arearefs="co-terminaloptions"><para>Only used if terminal is
needed</para>
</callout>
<callout arearefs="co-path"><para>Working directory for command</para>
</callout>
<callout arearefs="co-type"><para>More boiler plate</para>
</callout>
<callout arearefs="co-terminal"><para>Use true if terminal is needed,
text application</para>
</callout>
<callout arearefs="co-x-kde-startupnotify"><para>Show bouncy cursor,
disable if it doesn't work.</para>
</callout>
<callout arearefs="co-x-dcop-servicetype"><para>Has app started ok?
Remove if it doesn't work</para>
</callout>
<callout arearefs="co-categories"><para>Categories for &kde; Menu, not
used on desktop</para>
</callout>
</calloutlist>



</sect2>

<sect2 id="desktop-icons-exec">
<title>The <varname>Exec</varname> option in <literal
role="extension">.desktop</literal> files</title>

<para>Following the command, you can have several place holders which will
be replaced with the actual values when the actual program is run:
<variablelist>
<varlistentry>
<term>%f</term> <listitem><para>A single file name; used when dropping
file on icon, or with file associations.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%F</term>
<listitem><para>A list of files; use for applications that can
open several local files at once.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%u</term>
<listitem><para>A single &URL;: if the app can
handle &eg; &FTP; or &HTTP; &URL;s itself, otherwise &kde;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%U</term>
<listitem><para>A list of
&URL;s; will download the file first and pass a local file to the app
(!!)</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%d</term>
<listitem><para>The folder of the file to open; useful if app needs to
have file in current working directory.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%D</term>
<listitem><para>A list of folders, not very practical.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%i</term> 
<listitem><para>The icon; <option>--icon</option> option; &kde; app
will use icon from <varname>Icon</varname>= line in taskbar.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%m</term>
<listitem><para>The mini-icon; legacy.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>%c</term> 
<listitem><para>The caption; <option>--caption</option> option; &kde;
app will use name from <varname>Name</varname>= line in
taskbar.</para>
</listitem>
</varlistentry>

</variablelist>
</para>

<informalexample>
<para>Examples:
<segmentedlist>
<segtitle><varname>Exec</varname> line</segtitle>
<segtitle>Command executed</segtitle>
<seglistitem><seg>ksirc %i</seg><seg><command>ksirc --icon ksirc</command></seg>
</seglistitem>
<seglistitem><seg>cd %d; kedit $(basename %f)</seg><seg><command>cd /tmp; kedit file.txt</command></seg>
</seglistitem>
</segmentedlist>
</para>
</informalexample>

<!--Dont' know what this refers to: -->
<!--See What's This (Shift-F1) in Properties Dialog-->

</sect2>

<sect2 id="desktop-icons-devices">
<title>Devices</title>
<para>
Links to Devices using <literal role="extension">.desktop</literal> file:
o Create New -> Device

</para>
</sect2>

<sect2 id="where-to-define">
<title>Where to Define</title>

<para>Many places to define Desktop Icons:
<itemizedlist>

<listitem><para><filename class="directory">~/Desktop</filename>:
copied from <filename
class="directory">/etc/skel/Desktop</filename></para></listitem>

<listitem><para><filename
class="directory">$<envar>KDEDIR</envar>/apps/kdesktop/Desktop</filename>
(merged)</para></listitem>

<listitem><para><filename
class="directory">$<envar>KDEDIR</envar>/apps/kdesktop/DesktopLinks</filename>
(copied)</para></listitem>

<listitem><para>Device Icons (dynamically
merged)</para></listitem>

<listitem><para>Distribution Specific SUSE Linux copies certain icons
in startkde.theme from <filename
class="directory">/opt/kde3/share/config/SuSE/default/</filename></para></listitem>

</itemizedlist>
</para>
</sect2>
</sect1>

<sect1 id="kde-menu">
<title>&kde; Menu</title>

<sect2 id="how-it-works">
<title>How it Works</title>

<para>In &kde; 3.2 a common menu format is introduced at
<ulink
url="http://freedesktop.org/Standards/menu-spec/">http://freedesktop.org/Standards/menu-spec/</ulink></para>
<para>Before &kde; 3.2:
<itemizedlist>

<listitem><para>Directory structure under <filename
class="directory">share/applnk</filename></para></listitem>

<listitem><para>Directory structure represents menu
structure</para></listitem>

<listitem><para>Each <literal role="extension">.desktop</literal> file
represents a single application</para></listitem>

</itemizedlist>
</para>

<para>It was difficult to rearrange the structure in &kde; 3.2 so the
new menu format:
<itemizedlist>
<listitem><para>Defines structure in a single .menu file</para></listitem>
<listitem><para>Is based on categories</para></listitem>
<listitem><para>is shared between <acronym>GNOME</acronym> and &kde;</para></listitem>
<listitem><para>Supports applnk style menus as well</para></listitem>
</itemizedlist>
</para>

<informalexample>
<para>Example from <filename>applications.menu</filename>:
<programlisting>
<markup>
        &lt;Menu&gt;
            &lt;Name&gt;Office&lt;/Name&gt;
            &lt;Directory&gt;suse-office.directory&lt;/Directory&gt;
            &lt;Include&gt;
                &lt;Filename&gt;Acrobat Reader.desktop&lt;/Filename&gt;
                &lt;Filename&gt;kde-kpresenter.desktop&lt;/Filename&gt;
                &lt;Filename&gt;kde-kword.desktop&lt;/Filename&gt;
            &lt;/Include&gt;
        &lt;Menu&gt;
</markup>
</programlisting>
</para>
<para>Menu entry with 3 applications:
<itemizedlist>

<listitem><para><filename>/usr/share/applications/Acrobat
Reader.desktop</filename></para></listitem>

<listitem><para><filename>/opt/kde3/share/applications/kde/kpresenter.desktop</filename></para></listitem>

<listitem><para><filename>/opt/kde3/share/applications/kde/kword.desktop</filename></para></listitem>

</itemizedlist>
</para>
</informalexample>
</sect2>

<sect2 id="stored-where">
<title>Stored Where?</title>

<para><literal role="extension">.menu</literal> files describing the
menu structure. The files are stored in <filename
class="directory">$<envar>KDEDIR</envar>/etc/xdg/menus</filename> and
<filename class="directory">/etc/xdg/menus</filename>. These store the
system-wide menu structure and are controlled by
$<envar>XDG_CONFIG_DIRS</envar>. <filename
class="directory">$<envar>HOME</envar>/.config/menus</filename> stores
user-specific changes to the menu structure and is controlled by
$<envar>XDG_CONFIG_HOME</envar>. For more information, see <ulink
url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink>.</para>

<para><literal role="extension">.desktop</literal> files describe the
applications and are stored in: <filename
class="directory">$<envar>KDEDIR</envar>/share/applications</filename>,
<filename class="directory">/usr/share/applications</filename>,
<filename
class="directory">/usr/local/share/applications</filename>. These are
the system-wide application <literal
role="extension">.desktop</literal> files which are controlled by
$<envar>XDG_DATA_DIRS</envar>.</para>

<para><filename
class="directory">$<envar>HOME</envar>/.local/applications</filename>
contains user-specific <literal role="extension">.desktop</literal>
files and user-specific changes. It is controlled by
$<envar>XDG_DATA_HOME</envar>. For more information, see <ulink
url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink></para>


<para><literal role="extension">.directory</literal> files describing
the sub-menus are stored in: <filename
class="directory">$<envar>KDEDIR</envar>/share/desktop-directories</filename>,
<filename class="directory">/usr/share/desktop-directories</filename>, <filename
class="directory">/usr/local/share/desktop-directories</filename>.
These are the system-wide menu <literal
role="extension">.directory</literal> files, controlled by
$<envar>XDG_DATA_DIRS</envar>. The user-specific changes are stored in <filename class="directory">$<envar>HOME</envar>/.local/desktop-directories</filename>.
These are controlled by $<envar>XDG_DATA_HOME</envar>. For more
information, see <ulink url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink></para>

<informalexample>
<para>Example from <filename>applications.menu</filename>:
<programlisting>
<markup>
             &lt;Menu&gt;
                        &lt;Name&gt;Art&lt;/Name&gt;
                        &lt;Directory&gt;suse-edutainment-art.directory&lt;/Directory&gt;
                        &lt;Include&gt;
                                &lt;Category&gt;X-SuSE-Art&lt;/Category&gt;
                        &lt;/Include&gt;
                &lt;/Menu&gt;
</markup>
</programlisting>
</para>

<para><literal>Art</literal> is the internal name for this
menu. <filename>suse-edutainment-art.directory</filename> defines the
name and icon for this menu, and the menu includes all applications
that have <literal>X-SuSE-Art</literal> listed as a category, &eg;:
<programlisting>
Categories=Qt;KDE;Education;X-SuSE-Art
</programlisting></para>

<para><filename>suse-edutainment-art.directory</filename> defines the
name and icon for this menu:
<programlisting>
[Desktop Entry]
Name=Art and Culture
Icon=kcmsystem
</programlisting>
</para>
</informalexample>
</sect2>

<sect2 id="common-pitfalls">
<title>Common Pitfalls</title>

<para>Applications <emphasis>not</emphasis> in the menu do
<emphasis>not</emphasis> exist with regard to other applications or
file associations: If you remove an application from the menu, &kde; assumes you don't want to use it.</para>

<para>When applications are unwanted in the menu, either place them in
<filename>.hidden</filename> menu or a dedicated menu with 
<programlisting>
NoDisplay=true
</programlisting> in the <literal
role="extension">.directory</literal> file</para>
</sect2>

<sect2 id="essential-menus">
<title>Essential Menus</title>

<para><filename
class="directory">$<envar>KDEDIR</envar>/etc/xdg/menus/applications-merged/</filename>
contains <filename>kde-essential.menu</filename> which includes some
essential menus that are normally not shown in the &kde; menu itself:
<itemizedlist>
<listitem><para>Control Center has a hidden Settings menu whose
contents are defined by <filename>kde-settings.menu</filename> and
whose icon and name are defined by <filename>kde-settings.directory</filename></para>
</listitem>
<listitem><para>Info Center has a hidden Information menu whose
contents are defined by <filename>kde-information.menu</filename> and
whose icon and  name are  defined by <filename>kde-information.directory</filename>.</para>
</listitem>

<listitem><para>Screensavers contains a hidden System/Screensavers menu,
whose contents are defined by
<filename>kde-screensavers.menu</filename> and whose icon and  name
are defined by
<filename>kde-system-screensavers.directory</filename>.
<filename>$<envar>KDEDIR</envar>/share/desktop-directories/kde-system-screensavers.directory</filename>
contains:
<programlisting>
NoDisplay=true
</programlisting>
</para>
</listitem>
</itemizedlist></para>
</sect2>

<sect2 id="old-style-menus">
<title>Old-Style Menus</title>

<para>&kde; continues to support old-style menus that are defined by
the directory structures in <filename
class="directory">$<envar>KDEDIR</envar>/share/applnk</filename>
(system wide) and <filename
class="directory">$<envar>HOME</envar>/.kde/share/applnk</filename>
(user specific). This is observed unless the <literal role="extension">.desktop</literal> file has a  <varname>Categories</varname>= line. In that case the categories determine the location in the menu.</para>
</sect2>

<sect2 id="ksycoca">
<title><application>KSycoca</application></title>
<para><application>KSycoca</application> caches menu structure and
information about all available applications. You can rebuild the
database with
<userinput><command>kbuildsycoca4</command></userinput>. The database
which is built lives in <filename
class="directory">/var/tmp/kdecache-${<envar>USER</envar>}/ksycoca</filename>.
It is automatically updated by <application>KDED</application>,
checked during &kde; login, and <application>KDED</application>
watches for changes while logged in.</para>

<para>To disable watching for changes (since it may hurt over NFS) add
the following to <filename>kdedrc</filename>:
<programlisting>
[General]
CheckSycoca=false
</programlisting>
</para>

<para>To force regeneration, run <userinput><command>touch $<envar>KDEDIR</envar>/share/services/update_ksycoca</command></userinput>.</para>

</sect2>

<sect2 id="kmenuedit">
<title>&kmenuedit;</title>

<para>&kmenuedit; is aimed at a single user setup. Changes to menu
structure are saved to
<filename>~/.config/menus/applications-kmenuedit.menu</filename>,
changes to applications are saved in <filename
class="directory">~/.local/share/applications/</filename> and changes
to sub-menus (icon, name) are saved in <filename
class="directory">~/.local/share/desktop-directories/</filename>. The
KIOSK Admin Tool uses &kmenuedit; and copies the above changes to
profile- or system-wide locations.
</para>

</sect2>

</sect1>

<!-- This section might be redundant. If it isn't, it needs some screenies -->
<sect1 id="kde-panel">
<title>&kde; Panel</title>

<para>The &kde; panel is also known as &kicker;. It is modular and
consists of the following components:
<itemizedlist>
<listitem><para>Applets</para></listitem>
<listitem><para>Application buttons</para></listitem>
<listitem><para>Special Buttons</para></listitem>
</itemizedlist>
</para>

<para>By default, the panel contains the following applets:
<itemizedlist>
<listitem><para>Pager - shows the virtual desktops</para></listitem>
<listitem><para>Taskbar</para></listitem>
<listitem><para>System Tray</para></listitem>
<listitem><para>Clock</para></listitem>
</itemizedlist>
and the following special buttons:
<itemizedlist>
<listitem><para>&kde; menu</para></listitem>
<listitem><para>Desktop Button</para></listitem>
</itemizedlist>
</para>

<para>Various application buttons are also added, space permitting:
<itemizedlist>
<listitem><para>Home Button</para></listitem>
<listitem><para>Browser Button</para></listitem>
<listitem><para>KMail Button</para></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="file-associations">
<title>File Associations</title>

<para>File associations associate a file type with an application or
applications. The type of a file is established by determining its
&MIME; type. &MIME; types known by &kde; are stored in <filename
class="directory">$<envar>KDEDIR</envar>/share/mimelnk</filename> and
each application's <literal role="extension">.desktop</literal> file
contains a list of &MIME; types supported by that application.</para>

<informalexample>
<para><filename>kview.desktop</filename>:
<programlisting>
MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg;
image/x-bmp;image/png;image/x-ico;image/x-portable-bitmap;
image/x-portable-pixmap;image/x-portable-greymap;
image/tiff;image/jp2
</programlisting>
</para>

<para><filename>kuickshow.desktop</filename>:
<programlisting>
MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg;
image/png;image/tiff;image/x-bmp;image/x-psd;image/x-eim;
image/x-portable-bitmap;image/x-portable-pixmap;
image/x-portable-greymap
</programlisting>
</para>

<para>Both can open image/gif Which one is used to open a <literal role="extension">.gif</literal> file?</para>

<para>The application with highest
preference!. <filename>kview.desktop</filename> contains
<programlisting>
InitialPreference=3
</programlisting>
whereas <filename>kuickshow.desktop</filename> contains
<programlisting>
InitialPreference=6
</programlisting>
Therefore, &kuickshow; will be used to open <literal
role="extension">.gif</literal> files.
</para>

<para>How can we make &kview;  default?</para>

<para>A user can change file association in the
&kcontrolcenter;. These changes are stored in
<filename>$<envar>HOME</envar>/.kde/share/config/profilerc</filename>.
To use the same settings for multiple users, store these settings in
user profile directory or the global &kde; config directory to use as
default for multiple users.</para>

</informalexample>

</sect1>

</chapter>

<chapter id="locking-down-kde">
<title>Locking Down &kde;</title>

<sect1 id="how-it-works-the-basics">
<title>How It Works - The Basics</title>

<para>&kde;'s lock down features are centered around the following
options:</para>

<itemizedlist>
<listitem><para><link linkend="immutable-configuration-options">Make
configuration options immutable</link></para></listitem>
<listitem><para><link linkend="action-restrictions">Restriction of specific
actions</link></para></listitem>
<listitem><para><link linkend="url-restrictions">Restrict access to certain
&URL;s</link></para></listitem>
<listitem><para><link linkend="configuration-modules">Restrict access to
certain configuration modules</link></para></listitem>
</itemizedlist>

</sect1>

<sect1 id="immutable-configuration-options">
<title>Immutable Configuration Options</title>
<subtitle>Locking Down &kde;</subtitle>

<para>Immutable options allow system administrator to provide default
settings that can not be changed by the user.</para>

<para>Pre-existing configuration options of the user will be ignored once a
configuration option is made immutable.</para>

<para>Options can be controlled either on a per entry basis, per group of
entries or on a file by file basis.</para>

<para>If a file or group is immutable, all configuration options for that
file or group are immutable, even those options for which the system
administrator has no default provided.</para>

<note><para>The support in applications for immutable options may vary from
application to application. Although the user will not be able to make
permanent changes to immutable configuration options, the user may still be
presented with an user interface option to make such change.</para></note>

</sect1>

<sect1 id="action-restrictions">
<title>Action Restrictions</title>

<para>&kde; applications are built around the action-concept. Actions can be
activated in various ways, typically via the menu-bar, one of the toolbars
or a keyboard shortcut. <action>Save Document</action> is an example of an
action.  If you know the internal action name it is possible to restrict an
action. When an action is restricted it will no longer appear in the
menu-bar or toolbar. The internal name for the <action>Save
Document</action> action is <option>action/file_save</option>.  The lock
down framework also provides a set of more abstract restrictions which can
be used to disable functionality not covered by a single action. An example
is the <option>shell_access</option> restriction which disables all
functionality that would offer the user access to a &UNIX; shell.</para>

<example>
<title>Restrict User Access to Shells</title>

<para>In order to prevent the user access to a command shell we can restrict
the <option>shell_access</option> action by adding the following to
<filename>kdeglobals</filename>:
</para> 

<screen>[KDE Action Restrictions]
shell_access=false</screen>

<para>Since this affects the &kde; menu and the available applications, we
must force an update of the sycoca database:</para>

<screen><userinput><command>touch</command> <filename>$<envar>KDEDIR</envar>/share/services/update_ksycoca</filename></userinput></screen>

<para>Now re-login to &kde; and check the following points:</para>

<itemizedlist>
<listitem><para>The &kmenu;</para></listitem>
<listitem><para>In &konqueror;,
<menuchoice><guimenu>Tools</guimenu><guimenuitem>Open
Terminal</guimenuitem></menuchoice></para></listitem>
<listitem><para>The <keycombo
action="simul">&Alt;<keycap>F2</keycap></keycombo> run
command</para></listitem>
</itemizedlist>
</example>
<para>Full documentation about available actions can be found on <ulink
url="http://www.kde.org/areas/sysadmin/">http://www.kde.org/areas/sysadmin/</ulink>.</para>

<para>A few of the more interesting actions are listed below:</para>

<variablelist>
<varlistentry>
<term><option>action/options_configure</option></term>
<listitem><para>The <guimenuitem>Configure</guimenuitem> option form the
<guimenu>Settings</guimenu> menu</para></listitem>
</varlistentry>
<varlistentry>
<term><option>action/help_report_bug</option></term>
<listitem><para>The <guimenuitem>Report Bug</guimenuitem> option from the
<guimenu>Help</guimenu> menu.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>action/kdesktop_rmb</option></term>
<listitem><para>&RMB; mouse button menu on the desktop.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>action/kicker_rmb</option></term>
<listitem><para>&RMB; mouse button menu on the panel.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>user/root</option></term>
<listitem><para>Hide all actions or applications that require <systemitem
class="username">root</systemitem> access.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>shell_access</option></term>
<listitem><para>Hides all actions or applications that provide shell
access.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>print/system</option></term>
<listitem><para>Disables the option to select the printing system
(backend).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>lock_screen</option></term>
<listitem><para>Whether the user will be able to lock the
screen</para></listitem>
</varlistentry>
<varlistentry>
<term><option>start_new_session</option></term>
<listitem><para>Whether the user may start a second X session (see also
&kdm;)</para></listitem>
</varlistentry>
<varlistentry>
<term><option>opengl_screensavers</option></term>
<listitem><para>Whether OpenGL screensavers are allowed to be
used.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>manipulatescreen_screensavers</option></term>
<listitem><para>Permit screensavers that do not hide the entire
screen</para></listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="url-restrictions">
<title>&URL; Restrictions</title>

<para>There are three types of restrictions that can be applied to
&URL;s:</para>

<variablelist>
<varlistentry>
<term>list</term>
<listitem><para>To control whether a directory listing is
allowed.</para></listitem>
</varlistentry>
<varlistentry>
<term>open</term>
<listitem><para>To control whether certain &URL;s can be
opened</para></listitem>
</varlistentry>
<varlistentry>
<term>Redirect</term>
<listitem><para>To control whether one &URL; can open another &URL;, either
automatically or via a hyperlink.</para></listitem>
</varlistentry>
</variablelist>

<para>Rules are checked in the order in which they are defined.  The last
rule that is applicable to a &URL; defines whether the &URL; may be
accessed.</para>

<para>The following rules disable opening http and https &URL;s outside
<systemitem class="domainname">.ourcompany.com</systemitem>:</para>

<screenco><areaspec>
<area id="url_commas" coords="3"/>
<area id="url_rule1" coords="3"/>
<area id="url_rule2" coords="4"/>
</areaspec>
<screen>[KDE URL Restrictions]
rule_count=2
rule_1=open,,,,http,,,false
rule_2=open,,,,http,*.ourcompany.com,,true</screen></screenco>

<calloutlist>
<callout arearefs="url_commas">
<para>The first four commas skip over the selection criteria with respect to
the originating &URL;. This part is only needed with redirect type
rules.</para> 
</callout>
<callout arearefs="url_rule1"><para><option>rule_1</option> forbids the
opening of any http or https &URL;</para></callout>
<callout arearefs="url_rule2"><para><option>rule_2</option> allows the
opening of any http and https &URL; in the <systemitem
class="domainname">.ourcompany.com</systemitem> domain.  Note the wildcard
<token>*</token> is only allowed at the start of a domain.</para></callout>
</calloutlist>

<para>The following rules makes that the user can no longer browse
directories on the local file system that are outside his
$<envar>HOME</envar> directory:</para>

<screenco><areaspec>
<area id="home_rule1" coords="3"/>
<area id="home_rule2" coords="4"/>
</areaspec>
<screen>[KDE URL Restrictions]
rule_count=2
rule_1=list,,,,file,,,false
rule_2=list,,,,file,,$HOME,true</screen></screenco>

<calloutlist>
<callout arearefs="home_rule1"><para><option>rule_1</option> forbids the
listing of any local directory</para></callout>
<callout arearefs="home_rule2"><para><option>rule_2</option> allows listing
directories under the users own $<envar>HOME</envar>
directory.</para></callout>
</calloutlist>

<para>$<envar>HOME</envar> and $<envar>TMP</envar> are special values to
indicate the users home directory and the &kde; temporary directory of the
user, &eg; <filename class="directory">/tmp/kde-bastian</filename></para>

<para>The following rules makes that the user can no longer open local files
that are outside his $<envar>HOME</envar> directory:</para>

<screenco><areaspec>
<area id="local_rule1" coords="3"/>
<area id="local_rule2" coords="4"/>
<area id="local_rule3" coords="5"/>
</areaspec>
<screen>[KDE URL Restrictions]
rule_count=3
rule_1=open,,,,file,,,false
rule_2=open,,,,file,,$HOME,true
rule_3=open,,,,file,,$TMP,true</screen></screenco>

<calloutlist>
<callout arearefs="local_rule1"><para><option>rule_1</option> forbids the
opening of any local file</para></callout>
<callout arearefs="local_rule2"><para><option>rule_2</option> allows opening
files under the users own $<envar>HOME</envar> directory.</para></callout>
<callout arearefs="local_rule3"><para><option>rule_3</option> allows opening
files in the &kde; temporary directory of the user.  This is needed by
certain &kde; applications that first download a file or document to the
temporary directory and then open it in an application.</para></callout>
</calloutlist>


<para>The redirection option controls whether documents from a certain
location can refer, either automatically or manually via a hyperlink, to a
certain other location.  A set of default rules is present as a general
security measure. For example documents located on the Internet may not
refer to locally stored documents.</para>

<para>For example, if we want to give the intranet-server <systemitem
class="systemname">www.mycompany.com</systemitem> the possibility to refer
to local files we could add the following rule:</para>

<screen>[KDE URL Restrictions]
rule_count=1
rule_1=redirect,http,www.mycompany.com,,file,,,true</screen>

<para>Instead of listing a protocol by name, it is also possible to specify
a whole group of protocols. For that the following groups have been
defined:</para>

<variablelist>
<varlistentry>
<term>:local</term>
<listitem><para>Protocols that access locally stored information, examples
are file:/, man:/, fonts:/, floppy:/</para></listitem>
</varlistentry>
<varlistentry>
<term>:internet</term>
<listitem><para>Common internet protocols such as http and
ftp</para></listitem>
</varlistentry>
</variablelist>

<para>Information about protocols is stored in <literal
role="extension">*.protocol</literal> files stored in
<filename
class="directory">$<envar>KDEDIR</envar>/share/services</filename>.</para>

<para>The <option>Class</option>= entry defines the group a protocol is part
of:
<userinput><command>grep</command> <option>Class=</option>
<filename>$<envar>KDEDIR</envar>/share/services/*.protocol</filename></userinput></para>

<para>General rules:</para>

<itemizedlist>
<listitem><para>The :local protocols may refer to any other
protocol</para></listitem>
<listitem><para>It's always allowed to refer to an :internet
protocol</para></listitem>
<listitem><para>Not all protocols are part of a group, fish:/ for
example.</para></listitem>
</itemizedlist>

</sect1>

<sect1 id="configuration-modules">
<title>Configuration Modules</title>

<para>&kde; has configuration modules to configure various aspects of the
&kde; environment. Configuration modules appear in the Control Center, in the
Configuration dialog of an application or in both.</para>

<informalexample>
<para>The proxy configuration module appears in the Control Center but also
as part of the <guilabel>Configure Konqueror</guilabel> dialog in
&konqueror;</para>

<para>Individual configuration modules can be started with
<command>kcmshell4</command> <replaceable>module</replaceable></para>

<para>To start the Proxy module use:</para>
<itemizedlist>
<listitem><para><command>kcmshell4</command>
<filename>kde-proxy.desktop</filename></para></listitem>
<listitem><para><command>kcmshell4</command> proxy</para></listitem>
</itemizedlist>

<para><note><para>Not all applications use configuration modules, often the
configuration dialog is an integral part of the application
itself.</para></note></para>
</informalexample>

<para>All configuration modules are strictly speaking part of the &kde;
menu.</para>

<itemizedlist>
<listitem>
<para>The modules that are visible in the Control Center normally
have a <literal role="extension">.desktop</literal> file in <filename
class="directory">$<envar>KDEDIR</envar>/share/applications/kde</filename>
and are sorted under the hidden <guimenu>Settings-Modules</guimenu> menu by
the <filename>kde-settings.menu</filename>, included from 
<filename>kde-essential.menu</filename></para>
<screen><userinput><command>kbuildsycoca4</command> <option>--menutest</option> 2&gt; /dev/null | <command>grep</command> Settings-Modules</userinput></screen>
</listitem>
<listitem>
<para>Application specific modules normally have a <literal role="extension">.desktop</literal> file under
<filename>$<envar>KDEDIR</envar>/share/applnk/.hidden</filename> which
corresponds to the hidden .hidden menu, included as a result of
<markup>&lt;KDELegacyDirs/&gt;</markup></para>
<screen><userinput><command>kbuildsycoca4</command> <option>--menutest</option> 2&gt; /dev/null | <command>grep</command> .hidden</userinput></screen>
</listitem>
<listitem><para>In &kde; 3.3 it is possible to edit the Control Center with
<application>kcontroledit</application>.
<application>kcontroledit</application> works just like
<application>kmenuedit</application>, changes for current user only. Use
<application>kiosktool</application> to make changes for
everyone.</para></listitem> 
</itemizedlist>

<para>Individual configuration modules can be disables by adding the
following to <filename>kdeglobals</filename>:</para>

<screen>[KDE Control Module Restrictions]
<replaceable>module-id</replaceable>=false</screen>
<para>For example, to disable the proxy module use</para>
<screen>[KDE Control Module Restrictions]
kde-proxy.desktop=false</screen>
<para>Check the Control Center and the <guilabel>Configure
Konqueror</guilabel> dialog if the proxy configuration is still
there.</para>

</sect1>
<!-- 
<sect1 id="making-it-work">
<title>Making it Work</title>

Making It Work
KDE 3.2: Set $KDEDIRS from startkde script
Distribute profiles to all clients

</para>
</sect1>
-->
</chapter>

<chapter id="the-lazy-admin">
<title>The Lazy Admin</title>

<!-- This section appears to need quite a lot of additional words to -->
<!-- make sense. Perhaps it would be better to comment it out if it -->
<!-- can't be updated before the next release (Phil) -->
<!-- FIXME: Commented it out until it's got some more content fleshing it -->
<!-- out (Lauri)

<sect1 id="lazy-admin-overview">
<title>Overview</title>

<para>
The Lazy Admin
Overview
Deployment
        How to get &kde; available on many clients
Remote Desktop Sharing
Take a look at someone else desktop
DCOP
        The DCOP command line tool makes it possible to control &kde; applications from the command line
KDialog
        A versatile tool to use standard &kde; dialogs in your own scripts



Deployment
Thin Clients
Installing Software
= AutoYaST
= KickStart
Maintaining Settings
= /etc/kderc, other settings
= Use rsync to copy files around
= Shared filesystem such as NFS
o store profiles themselves on NFS



http://www.suse.de/~nashif/autoinstall/index.html

</para>
</sect1>
-->
<sect1 id="remote-desktop-sharing">
<title>Remote Desktop Sharing</title>

<para>Remote desktop sharing allows remote users to view and optionally
control the desktop of the current user.  The remote user needs to be sent
an invitation, and it is possible to create a password protected standing
invitation. This is ideal for tech support teams or administrators to gain
access to users desktops in order to troubleshoot or remedy a problem or
guide a user through a procedure.</para>

<para>Remote desktop sharing involves two applications: &krfb; (&kde; remote
frame buffer, a VNC server) and &krdc; (&kde; remote desktop connection; a
VNC client.)</para>

<para>&krfb; can be used by any user to create and manage invitations.
Invitations create a one time password that allows the recipient to connect
to your desktop.  By default it is valid for only one successful connection,
and expires after one hour if not used.</para>

<para>Incoming connections are handled by the kinetd kded module.  You can
use the command <userinput><command>dcop</command> kded kinetd
services</userinput> to see if it is running. &krfb; waits for connections
on port 5900 by default.  When an incoming connection is made, a dialog will
appear to ask for confirmation by the current user.</para>

<!-- TODO: Write a bit more here, with a walk through maybe? -->

</sect1>

<sect1 id="kde-diy">
<title>&kde; DIY - Building Your Own Tools</title>

<sect2 id="dcop">
<title>DCOP</title>

<para>
Desktop COmmunication Protocol, <acronym>DCOP</acronym>, is a lightweight mechanism for inter-process communication.  
<acronym>DCOP</acronym> allows the user to interact with programs that are currently running.
&kde; supplies two programs to utilitize <acronym>DCOP</acronym>: 
<application>dcop</application>, a command-line program, and 
<application>kdcop</application>, a <acronym>GUI</acronym> program.
</para>
<para>
A few notes about using <command>dcop</command>:
</para>

<para>
<itemizedlist>
<listitem>
<para>
<command>dcop</command> [options] [application [object [function [arg1] [arg2] ... ] ] ]
</para>
</listitem>
<listitem>
<para>
Applications that can open more than one window at a time will be listed as 
&lt;application&gt;-<acronym>PID</acronym>
</para>
</listitem>
<listitem>
<para>
All the arguments are case-sensitve.  setFullScreen and setfullscreen are two different functions.
</para>
</listitem>
<listitem>
<para>
The regular expression token * can be used in the application and object arguments.
<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> kon*</option></userinput>
konqueror-16006
konsole-8954
</screen>
</para>
</listitem>

</itemizedlist>

</para>

<para>Some example commands and their output are below:
</para>

<informalexample>
<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole*</option></userinput>
konsole-8954
</screen>
<para>One &konsole; is running with a <acronym>PID</acronym> of 8954.</para>

<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option></userinput>
KBookmarkManager-.../share/apps/kfile/bookmarks.xml
KBookmarkManager-.../share/apps/konqueror/bookmarks.xml
KBookmarkNotifier
KDebug
MainApplication-Interface
konsole (default)
konsole-mainwindow#1
ksycoca
session-1
session-2
session-3
session-4
</screen>
<para>Here you see that there are four sessions running.</para>

<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> konsole</option></userinput>
QCStringList interfaces()
QCStringList functions()
int sessionCount()
QString currentSession()
QString newSession()
QString newSession(QString type)
QString sessionId(int position)
void activateSession(QString sessionId)
void nextSession()
void prevSession()
void moveSessionLeft()
void moveSessionRight()
bool fullScreen()
void setFullScreen(bool on)
ASYNC reparseConfiguration()
</screen>
<para>Here are the options for the main &konsole; program.
</para>

<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> session-1</option></userinput>
QCStringList interfaces()
QCStringList functions()
bool closeSession()
bool sendSignal(int signal)
void clearHistory()
void renameSession(QString name)
QString sessionName()
int sessionPID()
QString schema()
void setSchema(QString schema)
QString encoding()
void setEncoding(QString encoding)
QString keytab()
void setKeytab(QString keyboard)
QSize size()
void setSize(QSize size)
</screen>
<para>Here are the options for the first session, session-1.</para>

<screen><prompt>&percnt; </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> konsole</option><option> setFullScreen</option><parameter> true</parameter></userinput>
</screen>
<para>This sets &konsole; to full screen.</para>

</informalexample>

<para>
When there is more than one application/object, which one should you use?
 Got a reference?
</para>
<screen><prompt>&percnt; </prompt><userinput><command>echo</command><option> $KONSOLE_DCOP</option></userinput>
DCOPRef(konsole-7547,konsole)

<prompt>&percnt; </prompt><userinput><command>dcop</command><option> $KONSOLE_DCOP</option><option> newSession</option></userinput>
session-6

<prompt>&percnt; </prompt><userinput><command>dcopstart</command><option> konsole</option></userinput>
konsole-9058


#!/bin/sh
konsole=$(dcopstart konsole-script)
session=$(dcop $konsole konsole currentSession)
dcop $konsole $session renameSession Local

session=$(dcop $konsole konsole newSession)
dcop $konsole $session renameSession Remote

session=$(dcop $konsole konsole newSession)
dcop $konsole $session renameSession Code
dcop $konsole $session sendSession 'cd /my/work/directory'

</screen>

</sect2>

<sect2 id="kdialog">
<title>KDialog</title>
<subtitle>&kde; DIY - Building Your Own Tools</subtitle>

<para>You can use &kde; dialogs from your own scripts, to combine the power
of &UNIX; shell scripting with the ease of use of &kde;.</para>

<screen><userinput><command>kdialog</command> <option>--msgbox 'You have new mail!'</option></userinput></screen>

<screen><userinput><command>kdialog</command> <option>--title 'New Mail'</option> <option>--msgbox 'You have new mail!'</option></userinput></screen>

<para>The <application>KDialog</application> part can be replaced via
<option>--caption</option> option</para>

<screen><userinput><command>kdialog</command> <option>--title 'New Mail'</option> <option>--msgbox 'You have new mail!'</option> <option>--dontagain myfile:mykey</option></userinput></screen>

<para>Saves whether to show again in
<filename>$<envar>KDEHOME</envar>/share/config/myfile</filename> (by writing
into this file the following lines:</para>

<screen>[Notification Messages]
mykey=false</screen>

<para>Instead of <option>--msgbox</option> you can also use
<option>--sorry</option> and <option>--error</option>, as appropriate.  For
instance, you might use <command>kdialog</command> <option>--sorry 'The
network can not be reached'</option> or <command>kdialog</command>
<option>--error 'Mail box can not be opened'</option>.</para>

<para>It is also possible to create message boxes that accept a yes or no
answer.</para>

<screen><command>kdialog</command> <option>--yesno 'Do you want to connect
to the Internet?'</option> <command>echo</command> <returnvalue>$?</returnvalue></screen>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Return Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row><entry>0</entry><entry>Yes, OK, Continue</entry></row>
<row><entry>1</entry><entry>No</entry></row>
<row><entry>2</entry><entry>Cancel</entry></row>
</tbody>
</tgroup>
</informaltable>

<para>Make sure to store the result in a variable if you do not use it
directly, the next command will fill $? with a new value You can use
<option>--dontagain</option> here as well, it will remember the users choice
and returns it the next times without showing the dialog any more.</para>

<para>Further variations are:</para>

<variablelist>
<varlistentry>
<term><option>--warningyesno</option></term>
<listitem>
<para>like <option>--yesno</option> but with a different
icon</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--warningcontinuecancel</option></term>
<listitem><para>With <guibutton>Continue</guibutton> and
<guibutton>Cancel</guibutton> buttons.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--warningyesnocancel</option></term>
<listitem><para>With <guibutton>Yes</guibutton>, <guibutton>No</guibutton>
and <guibutton>Cancel</guibutton> button.  For example:</para>
<screen><command>kdialog</command> <option>--warningyesnocancel 'Do you want
to save the changes?'</option></screen>
</listitem>
</varlistentry>
</variablelist>

<screen><command>kdialog</command> <option>--inputbox "Enter your name:" "YourName"</option></screen>

<para>The result is printed to stdout, to put it in a variable you can use
<userinput>name=$(kdialog --inputbox "Enter your name:"
"YourName")</userinput>.  The last argument is optional, it is used to
pre-fill the dialog.</para>

<screen><userinput><varname>password</varname>=$(<command>kdialog</command> <option>--password "Enter your password:"</option>)</userinput></screen>

<para>The <option>--dontagain</option> option does not work with
<option>--inputbox</option> or <option>--password</option></para>

<para>There are two dialogs that let the user make a choice from a
list:</para>

<variablelist>
<varlistentry>
<term><option>--menu</option></term>
<listitem>
<para>Lets the user select a single item from a list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--checklist</option></term>
<listitem>
<para>Lets the user select one or more items from a list.</para>
</listitem>
</varlistentry>
</variablelist>

<screen><userinput><varname>city</varname>=$(<command>kdialog</command> <option>--menu "Select a city" a London b Madrid c Paris d Berlin</option>)</userinput></screen>

<para><varname>$city</varname> will <returnvalue>a</returnvalue>, <returnvalue>b</returnvalue>, <returnvalue>c</returnvalue> or <returnvalue>d</returnvalue>.</para>

<screen><userinput><varname>city</varname>=$(<command>kdialog</command> <option>--checklist "Select cities" a London off b Madrid on c Paris on d Berlin off</option>)</userinput></screen>

<para>Madrid and Paris will be pre-selected.  The result with Madrid and
Paris selected will be <returnvalue>"b"</returnvalue>
<returnvalue>"c"</returnvalue>.</para>

<para>If you add the <option>--separate-output</option> option, it will put
<returnvalue>b</returnvalue> and <returnvalue>c</returnvalue> each on a line
of its own, making the result easier to process.</para>

<screen>file=$(kdialog --getopenfilename $HOME)
file=$(kdialog --getopenfilename $HOME "*.png *.jpg|Image Files")
file=$(kdialog --getsavefilename $HOME/SaveMe.png)
file=$(kdialog --getexistingdirectory $HOME)</screen>

</sect2>

</sect1>

</chapter>

&groupware-with-kontact;

</part>

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "part")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->