<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/trinity</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/trinity</filename>. (This is &SuSE;-specific; other distributions may use <filename class="directory">/usr</filename> or <filename class="directory">/usr/trinity</filename>)</para></listitem> <listitem><para><filename class="directory">/etc/opt/trinity</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/trinity/share/mimelnk/text/plain.desktop</filename></para></listitem> <listitem><para><filename class="directory">/etc/opt/trinity/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/trinity/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/trinity</filename>, <filename class="directory">/usr</filename>, <filename class="directory">/usr/trinity</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/trinity</filename>, <filename class="directory">/usr</filename>, <filename class="directory">/usr/trinity</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='~/.trinity' KDEROOTHOME='/root/.trinity' KDEDIRS='/opt/kde_staff:/opt/trinity' </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/trinityrc</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/trinity</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/trinity/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/trinity/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, ⪚: <programlisting> Color[$i]=blue </programlisting> </para> <para>A group of entries can be locked down by placing <userinput>[$i]</userinput> behind the group name, ⪚: <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/trinity/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/trinity/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é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é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é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é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> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd"> <kcfg> <kcfgfile name="korganizerrc"/> <group name="General"> <entry type="Bool" key="Auto Save"> <label>Enable automatic saving of calendar</label> <default>true</default> </entry> <entry type="Int" key="Auto Save Interval"> <default>10</default> </entry> </group> </kcfg> </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 & 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 kdeinit +kcminit +knotify and kwrapper ksmserver $KDEWM </programlisting> <para>The first line starts the <command>kdeinit</command> master process. The <command>kdeinit</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>kdeinit: Running...</computeroutput>. The arguments after <command>kdeinit</command> are the names of additional processes to be started. The <token>+</token> indicates that <command>kdeinit</command> needs to wait till the process has finished. <command>kdeinit</command> also starts <command>dcopserver</command>, <command>klauncher</command> and <command>kded</command>.</para> <para>The second of the two lines asks <command>kdeinit</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/trinity</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 kdeinit: Running... waba 23187 0.1 2.1 23200 11124 ? S 21:41 0:00 kdeinit: dcopserver --nosid waba 23189 0.2 2.4 25136 12496 ? S 21:41 0:00 kdeinit: klauncher waba 23192 0.7 2.8 25596 14772 ? S 21:41 0:00 kdeinit: kded waba 23203 0.8 3.4 31516 17892 ? S 21:41 0:00 kdeinit: 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>dcopserver</command>, <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</command> and <command>knotify</command>.</para> </sect2> <sect2 id="dcopserver"> <title><command>dcopserver</command></title> <para><command>dcopserver</command> is a daemon which provides inter-process communication (&DCOP;) facilities to all &kde; applications. The &DCOP; facilities are accessible from the command shell via the <command>dcop</command> command line tool. &DCOP; is essential for all &kde; applications.</para> <para>Some related files:</para> <variablelist> <varlistentry> <term><filename>$<envar>HOME</envar>/.DCOPserver_$<envar>HOSTNAME</envar>_$<envar>DISPLAY</envar></filename></term> <listitem><para>⪚ <filename>.DCOPserver_linux__0</filename>. Controlled by $<envar>DCOPAUTHORITY</envar></para> </listitem> </varlistentry> <varlistentry> <term><filename>/tmp/.ICE-unix/dcop<replaceable>pid</replaceable>-<replaceable>number</replaceable></filename></term> <listitem><para>⪚ <filename>dcop7634-1069677856</filename>. This is the file that the <filename>DCOPserver</filename> file above points to.</para> </listitem> </varlistentry> <varlistentry> <term><filename>$<envar>HOME</envar>/.ICEauthority</filename></term> <listitem><para>Authorization information controlled by $<envar>ICEAUTHORITY</envar></para> </listitem> </varlistentry> </variablelist> </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=kcmshell 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 DCOP </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, ⪚ <userinput>KDE_LANG=fr kprogram &</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>TDE_FULL_SESSION</envar></term><listitem><para> (Since &kde; 3.2) Automatically set to true by &kde; startup, it is used by ⪚ &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 (⪚ &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/trinity</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 & 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 (⪚ &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/trinity/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ë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 ⪚ &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/trinity/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>kde-applications.menu</filename>: <programlisting> <markup> <Menu> <Name>Office</Name> <Directory>suse-office.directory</Directory> <Include> <Filename>Acrobat Reader.desktop</Filename> <Filename>kde-kpresenter.desktop</Filename> <Filename>kde-kword.desktop</Filename> </Include> <Menu> </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/trinity/share/applications/kde/kpresenter.desktop</filename></para></listitem> <listitem><para><filename>/opt/trinity/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>kde-applications.menu</filename>: <programlisting> <markup> <Menu> <Name>Art</Name> <Directory>suse-edutainment-art.directory</Directory> <Include> <Category>X-SuSE-Art</Category> </Include> </Menu> </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, ⪚: <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>kbuildsycoca</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, ⪚ <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>kcmshell</command> <replaceable>module</replaceable></para> <para>To start the Proxy module use:</para> <itemizedlist> <listitem><para><command>kcmshell</command> <filename>kde-proxy.desktop</filename></para></listitem> <listitem><para><command>kcmshell</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>kbuildsycoca</command> <option>--menutest</option> 2> /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><KDELegacyDirs/></markup></para> <screen><userinput><command>kbuildsycoca</command> <option>--menutest</option> 2> /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 <application>-<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>% </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>% </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>% </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>% </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>% </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>% </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>% </prompt><userinput><command>echo</command><option> $KONSOLE_DCOP</option></userinput> DCOPRef(konsole-7547,konsole) <prompt>% </prompt><userinput><command>dcop</command><option> $KONSOLE_DCOP</option><option> newSession</option></userinput> session-6 <prompt>% </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: -->