diff options
Diffstat (limited to 'doc/khelpcenter/adminguide')
| -rw-r--r-- | doc/khelpcenter/adminguide/CMakeLists.txt | 9 | ||||
| -rw-r--r-- | doc/khelpcenter/adminguide/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/khelpcenter/adminguide/groupware-kontact.docbook | 596 | ||||
| -rw-r--r-- | doc/khelpcenter/adminguide/index.docbook | 2733 |
4 files changed, 3341 insertions, 0 deletions
diff --git a/doc/khelpcenter/adminguide/CMakeLists.txt b/doc/khelpcenter/adminguide/CMakeLists.txt new file mode 100644 index 000000000..ec8d87dac --- /dev/null +++ b/doc/khelpcenter/adminguide/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION khelpcenter/adminguide ) diff --git a/doc/khelpcenter/adminguide/Makefile.am b/doc/khelpcenter/adminguide/Makefile.am new file mode 100644 index 000000000..86108a74b --- /dev/null +++ b/doc/khelpcenter/adminguide/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = khelpcenter/adminguide + diff --git a/doc/khelpcenter/adminguide/groupware-kontact.docbook b/doc/khelpcenter/adminguide/groupware-kontact.docbook new file mode 100644 index 000000000..e1a8db623 --- /dev/null +++ b/doc/khelpcenter/adminguide/groupware-kontact.docbook @@ -0,0 +1,596 @@ +<chapter id="groupware-with-kontact"> + +<chapterinfo> +<authorgroup> +<author> +<personname> +<firstname>Marco</firstname> +<surname>Menardi</surname> +</personname> +<email>[email protected]</email> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</chapterinfo> +<title>Sharing data with &kontact; via <acronym>IMAP</acronym></title> + +<sect1 id="kontact-imap-intro"> +<title>Introduction</title> + +<para>For my small office, I was looking for a long time for a +<acronym>PIM</acronym> solution that let me share data, so my secretary and +I can share contacts, appointments and so on. Being a &tde; user, I've heard +about the Kroupware project and wait its completion. But when I saw how +complicated is the architecture and setup of the +<application>Kolab</application> server 1.0 (the server side of the +project), I gave up, waiting for an easier to deploy +<application>Kolab</application> 2.0. In any case, the +<application>Kolab</application> stuff was clearly too much for my +needs. Fortunately in the &tde; wiki I've found some piece of +<acronym>IRC</acronym> conversation where they were talking about sharing +data without the <application>Kolab</application> infrastructure... mmm so +interesting!</para> + +<para>For small offices and needs, you can have &kontact; use shared data +without the need of installing the <application>Kolab</application> server +or another groupware backend. It can work with just an +<acronym>IMAP</acronym> server, that can be easily set up.</para> + +<para>My scenario is a server with Debian unstable and &kde; 3.4. I access +&kontact; and other fabulous GNU/Linux apps from windows using Cygwin/X, +while waiting Wine project to be able to run the last Windows programs I +need (and that are not available under GNU/Linux). I want to share contacts, +events, todo, notes with my secretary.</para> + +</sect1> + +<sect1 id="kontact-imap-whatis"> +<title>What is <acronym>IMAP</acronym></title> + +<para>This definition is from the <ulink +url="http://computeruser.com">ComputerUser.com High-Tech Dictionary:</ulink> +<blockquote><para>Internet Message Access Protocol. A protocol that allows a +user to perform certain electronic mail functions on a remote server rather +than on a local computer. Through IMAP the user can create, delete, or +rename mailboxes; get new messages; delete messages; and perform search +functions on mail. A separate protocol is required for sending mail. Also +called Internet Mail Access Protocol.</para></blockquote> </para> + +<para>So it can be considered a data storage. To use it you you need an +<acronym>IMAP</acronym> server, such as <application>Cyrus</application>, +<application>Courier</application> or <application>UW</application>.</para> + +</sect1> + +<sect1 id="kontact-kolab-or-imap"> +<title><application>Kolab</application> or <acronym>IMAP</acronym>?</title> + +<para><application>Kolab</application> brings the ability to share data +between different clients. It makes possible for your secretary to use +<application>Outlook</application> and you use &kontact;, for +instance.</para> + +<para>You will have a configuration interface which does user management, mail +account setup, a central <acronym>LDAP</acronym> config data and addressbook +server, spam and virus filtering, vacation scripts, free busy list handling, +resource handling (rooms, cars), groups, distribution lists, automatic +invitation handling, &etc;</para> + +<para>But that can cause initial setup troubles. For a newbie like me it +means: a long long frustrating nightmare, and too much complexity to manage +once working. So no, thanks, I'll go to simple +<acronym>IMAP</acronym>.</para> + +</sect1> + +<sect1 id="kontact-imap-cyrus"> +<title>How to set up <acronym>IMAP</acronym> server <application>Cyrus</application></title> + +<para>My choice is <application>Cyrus</application>, that is part of the +<application>Kolab</application> set of software, so if l will go for +<application>Kolab</application> in the future, at least I'm acquainted with +it.</para> <para>Let's start the installation and the setup!</para> + +<para>Become <systemitem class="username">root</systemitem>.</para> + +<screen># <userinput><command>apt-get</command> <command>install</command> cyrus21-imapd cyrus21-common cyrus21-admin cyrus21-client sasl-bin sasl2-bin</userinput> +<computeroutput>Installing cyrus21-imapd...</computeroutput><lineannotation>The installer asks something I've not understood about an search address... I just pressed <keycap>Enter</keycap></lineannotation>.</screen> + +<para>The installer also created the user <systemitem +class="username">cyrus</systemitem> that is in the (automatically created) +group <systemitem class="groupname">sasl</systemitem>, that is the +<quote>owner</quote> of all cyrus files. At the end with <command>ps +<option>-A</option></command> you can find the new processes: +<command>cyrmaster</command> and <command>notifyd</command>.</para> + +<para>The real problem in setting up <application>Cyrus</application> is the +authentication, just because it's not trivial and I'm a newbie, with limited +knowledge about what I'm doing.</para> + +<para><application>Cyrus</application> can use different +<acronym>SASL</acronym> (Simple Authentication and Security Layer) +mechanisms, the default being sasldb (it stores usernames and passwords in +the SASL secrets file <filename>sasldb</filename>), but also getpwent, +kerberos4, kerberos5, PAM, rimap, shadow and LDAP are supported.</para> + +<para> Since I don't want to define users/passwords different than the ones +that access my &Linux; box I choose then <quote>shadow</quote> mechanism so +<application>Cyrus</application> will use &Linux; passwords for +authenticate.</para> + +<para>To do so we have to tell sasl to use <command>saslauthd</command> as +password authentication method, and then setup <command>saslauthd</command> +to use <quote>shadow</quote> (or <quote>getpwent</quote>) as the +authentication mechanism.</para> + +<para>OK, let's start!</para> + +<para>As <systemitem class="username">root</systemitem>, change the Linux +password of <systemitem class="username">cyrus</systemitem> user:</para> + +<screen># <userinput><command>passwd <option>cyrus</option></command></userinput></screen> + +<para>Enter the password you like (and you will remember) we will use for +this example <quote>cyrus</quote> as the <application>cyrus</application> +administrator password.</para> + +<screen># <command>vi</command> <filename>/etc/imapd.conf</filename></screen> + +<programlisting>sasl_pwcheck_method: <userinput>saslauthd</userinput> <lineannotation>instead of the default <literal>auxprop</literal></lineannotation></programlisting> + +<para>remove the <literal>#</literal> remark from the line:</para> + +<programlisting>#admins: cyrus</programlisting> + +<para>this way you can administer <application>cyrus</application> logging +in as <systemitem class="username">cyrus</systemitem> user (what a fantasy I +have!)</para> + +<screen># <userinput><command>vi</command> <filename>/etc/default/saslauthd</filename></userinput></screen> + +<para>Uncomment the line:</para> + +<programlisting># START=yes</programlisting> + +<para>(otherwise the <application>saslauthd</application> will not start at +boot time, even if referenced in some <filename +class="directory">/etc/rcx.d</filename>!)</para> + +<para>and instead of <literal>MECHANISMS="pam"</literal> put +<userinput>MECHANISMS="shadow"</userinput> this way at the boot a +<command>saslauthd</command> <option>-a +<parameter>shadow</parameter></option> will be executed.</para> + +<para>Once exited from your editor, restart <application>sasl</application> +and <application>cyrus</application>.</para> + +<para>To test <acronym>IMAP</acronym>:</para> + +<screen> <userinput><command>su</command> <option>cyrus</option></userinput> +$ <userinput><command>imtest</command> <option>-m login -p imap localhost</option></userinput></screen> + +<para>You are prompted for the <systemitem +class="username">cyrus</systemitem> (user) password, so enter it.</para> + +<para>If the user <systemitem class="username">cyrus</systemitem> is +correctly authenticated, the following lines will appear:</para> + +<screen><computeroutput>S: L01 OK User logged in +Authenticated.</computeroutput></screen> +<para>To exit type <userinput>. logout</userinput> (&ie; dot space <quote>logout</quote>)</para> + +<para>Now add a user named <systemitem +class="username">groupware</systemitem> and set a password for it, using +your usual system tools. It should be in an unprivileged group such as +<systemitem class="groupname">nobody</systemitem> and does not require a +login shell or a home directory.</para> + +<para>Now I have to create the user and an <acronym>IMAP</acronym> in +<application>cyrus</application> also:</para> + +<screen># <userinput><command>cyradm</command> <option>--user cyrus localhost</option></userinput> +after entering the password for the admin user <systemitem class="username">cyrus</systemitem>, you get the prompt <prompt>localhost></prompt> +<prompt>localhost></prompt> <userinput><command>cm</command> <option>user.groupware</option></userinput> +<prompt>localhost></prompt> <userinput><command>lm</command></userinput> <lineannotation>lists the mailbox only just created</lineannotation> +<computeroutput>user.groupware (\HasNoChildren))</computeroutput> +<prompt>localhost></prompt> <userinput><command>quit</command></userinput></screen> + +<para>You can type <userinput><command>help</command></userinput> for a list +of available commands.</para> + +<para>You can check what has happened with:</para> + +<screen># <userinput><command>ls</command> <option>-l</option> <filename class="directory">/var/spool/cyrus/mail/g/user/groupware</filename></userinput> +<computeroutput>total 12 +-rw------- 1 cyrus mail 4 Oct 29 20:55 cyrus.cache +-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header +-rw------- 1 cyrus mail 76 Oct 29 20:55 cyrus.index</computeroutput></screen> + +<para>Now you should be able to connect with an <acronym>IMAP</acronym> client +as the <systemitem class="username">groupware</systemitem> user and see the +<literal>INBOX</literal>.</para> +<note><para>In the <acronym>IMAP</acronym> protocol, selecting the mailbox +<literal>INBOX</literal> is a magic word, a sort of <quote>alias</quote> for +the above directory structure. The client sees <literal>INBOX</literal>, and +the <acronym>IMAP</acronym> server maps it in the <filename +class="directory">/var/spool/cyrus/mail/...</filename> folder and file +structure.</para></note> + +</sect1> + +<sect1 id="kontact-imap-clients"> +<title>How to setup &kontact; clients</title> + +<para>I connect to my GNU/Linux office server PC (a sort of "black box" +without monitor and keyboard) from 2 &Windows; 2000 PC with +<application>Cygwin/X</application>, using them as a X-Window server (in the +near future I hope to replace both with 2 mini-itx thin clients using the +LTSP). With this setup every user runs &kontact; on the same machine where +<application>Cyrus</application> is installed and running +(localhost).</para> + +<para>To have &kontact; work with <acronym>IMAP</acronym>, there are these +steps to complete:</para> + +<procedure> + +<step><para>Create an <acronym>IMAP</acronym> account on the +<application>Cyrus</application> for fake <systemitem +class="username">groupware</systemitem> user (already previously +done!)</para></step> + +<step><para>Create/configure an <acronym>IMAP</acronym> account in &kmail; +for login as that user</para></step> <step><para>Use tderesources to make +&kontact; components work with data taken from <acronym>IMAP</acronym> +source</para></step> + +<step><para>Enable groupware functionality and make related subfolders of +that <acronym>IMAP</acronym> <literal>INBOX</literal> (if not +already)</para></step> + +<step><para>Enjoy &kontact; and shared data through +<application>Cyrus</application> IMAP</para></step> + +</procedure> + +<para>So login to &tde; with the first <quote>real user</quote> account you +want to provide groupware functionality to.</para> + +<para>Let's create the IMAP account in &kmail;.</para> + +<para>Run &kontact; and select <guilabel>Mail</guilabel> (the &kmail; +component). From the menu choose +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KMail +</guimenuitem><guilabel>Accounts</guilabel><guilabel>Receiving</guilabel></menuchoice> tab, press the <guibutton>Add...</guibutton> button. You will then be +prompted for the type of your email account, and select +<guilabel>disconnected IMAP</guilabel> (not just +<guilabel>IMAP</guilabel>). Then in the <guilabel>General</guilabel> tab +enter the following data:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Account Name:</guilabel> <userinput>office_gwdata</userinput></term> +<listitem> +<para>A name that will be used for the <quote>local</quote> folder that +points to this <acronym>IMAP</acronym> account.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Login:</guilabel> <userinput>groupware</userinput></term> +<listitem> +<para>The <application>Cyrus</application> user we have chosen as +<quote>owner</quote> of all of the office data</para> +</listitem> +</varlistentry> +<varlistentry><term><guilabel>Password:</guilabel></term> +<listitem> +<para>The password of the <systemitem +class="username">groupware</systemitem> user.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Host:</guilabel> <userinput>localhost</userinput></term> +<listitem> +<para>Remember for our example, the &kontact; client runs on the same +computer as the <acronym>IMAP</acronym> server</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Port:</guilabel> <userinput>143</userinput></term> +<listitem> +<para>The default</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Check <guilabel>store IMAP password</guilabel> +so you will not be asked for it next time you run &kontact;. Check the +<guilabel>Enable interval mail checking</guilabel> and set a value in +minutes.</para> + +<para>Note that we have checked the <guilabel>disconnected IMAP</guilabel> +type account. This has the effect that a copy of the groupware data is +stored <quote>locally</quote> to the client (under the home folder), and it +is synchronized every time the client connects. This seems very inefficient, +since your data is duplicated many times (&ie; if you have 10 users that use +&kontact;, you have 10+1 times the data), but it is the only way to make +things run fast, because at every connection &kontact; has to fetch all data +and have &korganizer; and &kaddressbook; interpret it. If you use +<quote>disconnected IMAP</quote> data is cached locally, and only the +<quote>delta</quote> (&ie; the data that has changed) is sent.</para> + +<para>On the other end, if your users run &korganizer; on the same PC that +runs the <acronym>IMAP</acronym> server, it seems reasonable to use +<acronym>IMAP</acronym> (that is called <quote>online IMAP</quote>) to save +space, since transfer speed should not be an issue. But unfortunately this +does not work because &kontact; does not update automatically the +<guilabel>Calendar</guilabel> folder in <quote>online IMAP</quote>, so you +are not updated when someone adds events (you must manually switch to +&kmail; application and click on the <guilabel>Calendar</guilabel> +folder). In addition, at start up when it does read +<guilabel>Calendar</guilabel> folders, you may see a tremendous flicker and +slow data updates.</para> + +<para>Now we have to tell &kontact; to use <acronym>IMAP</acronym> as the +data source for it's various components. From the &kmenu;, choose +<guimenuitem>Run command</guimenuitem>, run <userinput><command>tdecmshell +tderesources</command></userinput>. In the combo box select +<guilabel>Contacts</guilabel>, then press the <guibutton>Add...</guibutton> +button, and choose <guilabel>Addressbook on IMAP Server via KMail</guilabel>. Then select that new line and +press <guibutton>Use as Standard</guibutton> button. Do the same for +<guilabel>Calendar</guilabel> and <guilabel>Notes</guilabel>.</para> + +<para>Now we have to enable the &kmail; (and as a consequence, the whole +&kontact;) groupware functionality:</para> + +<procedure> +<step> +<para>Choose from the menu +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KMail</guimenuitem><guilabel>Misc</guilabel><guilabel>Groupware</guilabel></menuchoice></para> +</step> +<step> +<para>Check <guilabel>Enable IMAP resource functionality</guilabel></para> +</step> +<step> +<para>Choose <guilabel>English</guilabel> as <guilabel>Language of the +groupware folders</guilabel> (this is in case you already have the folders +in the <acronym>IMAP</acronym> server created by a different program in a +different language).</para> +</step> +<step> +<para>Now move to <guilabel>Resource folder are in account</guilabel> and +select the the <guilabel>Inbox</guilabel> subfolder of the +<guilabel>office_gwdata</guilabel> folder.</para> +<para>Leave <guilabel>Hide groupware folders</guilabel> unchecked for now, +so we can see that happens. You can return here and check it once everything +is clear.</para> +</step> +<step> +<para>When you press OK you are prompted with: +<computeroutput>&kmail; will now create the required folders for the IMAP +resource as subfolders of Inbox</computeroutput> </para> +<para>If you do not want this, press <guibutton>No</guibutton>, and the +<acronym>IMAP</acronym> resource will be disabled. Press +<guibutton>Yes</guibutton> (this happens only the first time with the first +<quote>real user</quote>). You will immediately see that in the &kmail; +folder tree, under +<menuchoice><guilabel>office_gwdata</guilabel><guilabel>Inbox</guilabel></menuchoice> +these subfolders are created:</para> +<simplelist> +<member>Calendar</member> +<member>Contacts</member> +<member>Notes</member> +<member>Tasks</member> +<member>Journal</member> +</simplelist> +<para>if you now do a:</para> +<screen># <command>ls</command> <option>-l /var/spool/cyrus/mail/g/user/groupware/</option> +<computeroutput>drwx------ 2 cyrus mail 144 Oct 31 16:36 Calendar +drwx------ 2 cyrus mail 144 Oct 31 16:36 Contacts +drwx------ 2 cyrus mail 144 Oct 31 16:36 Journal +drwx------ 2 cyrus mail 144 Oct 31 16:36 Notes +drwx------ 2 cyrus mail 144 Oct 31 16:36 Tasks +-rw------- 1 cyrus mail 4 Oct 31 15:28 cyrus.cache +-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header +-rw------- 1 cyrus mail 76 Oct 31 15:28 cyrus.index</computeroutput></screen> + +<para>As you see, the <guilabel>office_gwdata Inbox</guilabel> is stored not +local to the &kontact; current user home, but in the <acronym>IMAP</acronym> +<systemitem class="username">groupware</systemitem> user's folders.</para> +</step> +</procedure> + +<para>Now &kontact; is ready to work and store data there. In the calendar +application, if &kmail; <acronym>IMAP</acronym> account was of type +<quote>disconnected</quote>, the <guilabel>resource</guilabel> window should +display the item <guilabel>Imap resource</guilabel> with 3 subitems, that +are paths to local home files. Instead, the <guilabel>Contacts</guilabel> +application does not show subitems below the <guilabel>Imap +resource</guilabel>.</para> + +<para>You can now login to &tde; with a different username and set up +his/her &kontact; client in a very similar manner:</para> + +<procedure> +<step> +<para>Open &kontact; and in the <guilabel>Mail</guilabel> component add an +<acronym>IMAP</acronym> account specifying as <guilabel>host</guilabel> the +computer where <application>Cyrus</application> server runs (in my case: +<literal>192.168.1.3</literal>).</para> + +<para>Remember to check the <guilabel>Enable interval mail +checking</guilabel> and set a value in minutes. When you confirm, you are +not prompted for the subfolder creation (since they are found in the +<acronym>IMAP</acronym> server), and you see them in the folder tree.</para> +</step> +<step> +<para>Activate the groupware functionality to be able to save data in the +<acronym>IMAP</acronym> server.</para> +</step> +</procedure> +<para>Beware that in <quote>disconnected <acronym>IMAP</acronym></quote>, +data are transmitted from a client to <acronym>IMAP</acronym> server only +when the clients connects to check for new mail. So if you have your +&kontact; clients with an <guilabel>interval mail checking</guilabel> of, +for instance, 5 minutes, in the worst case you have a 10 minutes delay +between the event being written and it's appearance to the other +users.</para> +</sect1> +<sect1 id="kontact-imap-readonly"> +<title>How to have Read Only Access</title> + +<note><para>Beware that I've been confirmed that Notes +<acronym>IMAP</acronym> implementation in &kontact; prior to version 1.01 is +broken, so this setup will not work for them, so you want to use them, you +need to use the previous setup.</para></note> + +<para>In the previous setup, we have the same <quote>fake</quote> user, named +<systemitem class="username">groupware</systemitem>, that is used by all the +<quote>real</quote> &kontact; users (&ie; <systemitem +class="username">tony</systemitem>, <systemitem +class="username">rohn</systemitem>, <systemitem +class="username">amanda</systemitem>, &etc;) through the +<acronym>IMAP</acronym> account with it's login and password. But this way +every real user has the same read/write permissions of the others, since +everyone connects as the user <systemitem +class="username">groupware</systemitem> to the <acronym>IMAP</acronym> +server.</para> + +<para>To limit access to some users (typically, providing read-only access), +we can use the <acronym>ACL</acronym> (Access Control Lists).</para> + +<para>Select in &kmail; a subfolder of <guilabel>office_gwdata</guilabel> +inbox, for instance <guilabel>Calendar</guilabel>, and right click the +mouse. Select <guilabel>Properties</guilabel><guilabel>Access +Control</guilabel> tab. Here you can enter the users you want give access to +this folder and what they can do.</para> + +<para>Just to experiment trying to exchange events, we give +<quote>All</quote> permission to the user <systemitem +class="username">mary</systemitem></para> + +<para>At <application>cyrus</application> level (in the +<acronym>PC</acronym> that runs <acronym>IMAP</acronym> server cyrus, with +<application>cyrus</application> tools), we first need to add the user +<systemitem class="username">mary</systemitem>, so it's an +<acronym>IMAP</acronym> recognized user, and create an +<acronym>IMAP</acronym> folder for her.</para> + +<para>Then we login to GNU/Linux as <systemitem +class="username">mary</systemitem> and enter &kontact;. As previously shown, +we will setup an <acronym>IMAP</acronym> account in &kmail; with the same +data but the one of the user (instead of the fake user <systemitem +class="username">groupware</systemitem> and it's password, we will use +<systemitem class="username">mary</systemitem> and her password).</para> + +<para>In &kmail; folder tree, this time you will see this structure: +<menuchoice><guimenu>office_gwdata</guimenu><guisubmenu>user</guisubmenu> +<guisubmenu>groupware</guisubmenu><guimenuitem>Calendar and +Tasks</guimenuitem></menuchoice>. Check the mail +(<menuchoice><guimenu>File</guimenu><guimenuitem>Check +Mail</guimenuitem></menuchoice>) and you will also have an +<quote>inbox</quote> folder under <quote>office_gwdata</quote>.</para> + +<para>Now enable &kmail; groupware functionality, and in <guilabel>Resource +folders are subfolders of</guilabel> put the +<guimenuitem>inbox</guimenuitem> that is subfolder of +<quote>office_gwdata</quote>.</para> + +<para>Now enable &kmail; groupware functionality, and in <guilabel>Resource +folders are subfolders of</guilabel> put the +<guimenuitem>inbox</guimenuitem> that is subfolder of +<guisubmenu>office_gwdata</guisubmenu>.</para> + +<para>Now you have two branches of folder under +<quote>office_gwdata</quote>:</para> + +<orderedlist> +<listitem> +<para><quote>inbox</quote> with Calendar, Contacts, Notes, Tasks and +Journal, that are saved on <systemitem class="username">mary</systemitem> +<acronym>IMAP</acronym> folders on the <acronym>IMAP</acronym> server</para> +</listitem> +<listitem> +<para><quote>user</quote>, with the subfolder <quote>groupware</quote> and +the subfolders to which <systemitem class="username">mary</systemitem> has +access to (in this example, Calendar and Tasks)</para> +</listitem> +</orderedlist> +<para>&RMB; click on the <quote>user</quote> <quote>Calendar</quote> and +check if it's of type Calendar (if not, set it to be), and also if +<quote>user</quote><quote>Tasks</quote> is of type Tasks.</para> +<para>Now in Calendar you have two available <acronym>IMAP</acronym> +resources to write against, so if you create a new event, you are prompted +which one use (or if you left the local resources available, you have +3!).</para> +<para>You have go to the lower left small window in Calendar, the one that +shows available resources, and uncheck the ones that don't point to +<guilabel>.groupware.directory</guilabel> path (see the tail part of each +resource path).</para> + +</sect1> + +<sect1 id="kontact-imap-credits"> +<title>Credits</title> + +<para>I'm a newbie, and for this howto I've only provided my time and my +will. For the knowledge I have really to thank some guys in freenode +channels for their competence, patience and helpfulness.</para> + +<itemizedlist> +<title>Special thanks to:</title> +<listitem> +<para>For the <application>Cyrus</application> <acronym>IMAP</acronym> part +in #cyrus channel:</para> +<itemizedlist> +<listitem> +<para>[protagonist] Andy Morgan <email>[email protected]</email></para> +</listitem> +<listitem> +<para>[plixed] Okke Timm <email>[email protected]</email></para> +</listitem> +</itemizedlist> +</listitem> +<listitem> +<para>For the &kontact; part in #kontact channel:</para> +<itemizedlist> +<listitem> +<para>[till] Till Adam <email>[email protected]</email></para> +</listitem> +<listitem> +<para>[dfaure] David Faure <email>[email protected]</email></para> +</listitem> +<listitem> +<para>[mdouhan] Matt Douhan <email>[email protected]</email></para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> + +<para>Thank a lot guys!</para> + +<para>Ah, and there is also me, [markit] Marco Menardi +<email>[email protected]</email></para> + +</sect1> + +<sect1 id="kontact-imap-further-reading"> +<title>Further Reading</title> + +<itemizedlist> +<title>Reference</title> +<listitem><para>KDE: <ulink url="http://www.kde.org">http://www.kde.org</ulink></para></listitem> +<listitem><para>&kontact; website: <ulink url="http://www.kontact.org">http://www.kontact.org</ulink></para></listitem> +<listitem><para>Kroupware project: <ulink url="http://www.kroupware.org">http://www.kroupware.org</ulink></para></listitem> +<listitem><para>&kde; Community Wiki: <ulink url="http://wiki.kde.org">http://wiki.kde.org</ulink></para></listitem> +<listitem><para>Wine project: <ulink url="http://www.winehq.org">http://www.winehq.org</ulink></para></listitem> +<listitem><para>Cygwin/X project <ulink url="http://x.cygwin.com">http://x.cygwin.com</ulink></para></listitem> +<listitem><para>LTSP project: <ulink url="http://www.ltsp.org">http://www.ltsp.org</ulink></para></listitem> +</itemizedlist> + +</sect1> + +</chapter> diff --git a/doc/khelpcenter/adminguide/index.docbook b/doc/khelpcenter/adminguide/index.docbook new file mode 100644 index 000000000..dd24a1cdc --- /dev/null +++ b/doc/khelpcenter/adminguide/index.docbook @@ -0,0 +1,2733 @@ +<?xml version="1.0" ?> + <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY % addindex "INCLUDE"> + <!ENTITY % imageobjectco.module "INCLUDE"> + <!ENTITY groupware-with-kontact SYSTEM "groupware-kontact.docbook"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> + +<title>The &tde; (Trinity Desktop Environment) Administrator Guide</title> + +<authorgroup> +<author>&tde-authors;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2004-2005</year> +<holder>The &kde; Team</holder> +</copyright> +<copyright> +<year>&tde-copyright-date;</year> +<holder>&tde-team;</holder> +</copyright> + +<!-- <legalnotice>&FDLNotice;</legalnotice> --> + +<date>&tde-release-date;</date> +<releaseinfo>&tde-release-version;</releaseinfo> + +<abstract> +<para>A general administrator guide to the Trinity Desktop Environment. +</para> + +<para>Please report problems with this document to +<email>[email protected]</email>. +</para> +</abstract> + +<keywordset> +<keyword>TDE</keyword> +<keyword>administration</keyword> +<keyword>desktop</keyword> +<keyword>handbook</keyword> +<keyword>tutorial</keyword> +</keywordset> + +</bookinfo> + +<chapter id="tde-for-admins-introduction"> +<title>&tde; for Administrators</title> + +<sect1 id="tde-for-admins-overview"> +<title>Overview</title> + +<para>This handbook is a reference guide to +some &tde; features that are useful to administrators configuring +multi-user systems. This guide also has information useful +to &tde; users with single-user systems: where configuration files are +stored, what environment variables affect &tde;, and so on. The KIOSK +framework is the &tde; system that allows administrators to limit +what users can do in &tde;. That framework is useful in many +situations, but especially for running single-function kiosks with, +for example, only a web browser, hence the name.</para> + +</sect1> + +<sect1 id="directory-layout"> +<title>Directory Layout</title> + +<para>&tde; defines a filesystem hierarchy which is used by the &tde; +environment itself as well as all &tde; applications. In general &tde; +stores all its files in a directory tree with a fixed structure. +</para> + +<para>By default &tde; 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"> +~/.trinity</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>For example:</para> + +<itemizedlist> +<listitem><para><filename +class="directory">$<envar>HOME</envar>/.trinity</filename></para></listitem> +<listitem><para><filename +class="directory">/opt/trinity</filename>. (This location is a +typical default. Some distributions might use +<filename class="directory">/usr</filename> or <filename +class="directory">/usr/trinity</filename>)</para></listitem> +<listitem><para><filename +class="directory">/etc/trinity</filename>.</para></listitem> +</itemizedlist> + +<para>If you have the KIOSK Admin tool installed you can +check which directory trees are used with the following command: +<userinput><command>kiosktool-tdedirs</command> +<option>--check</option></userinput></para> +</informalexample> + +<para>&tde; and &tde; applications look up files by scanning all the +&tde; 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>/.trinity/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/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>/.trinity/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>/.trinity/share/config/foobar</filename></term> +<listitem><programlisting> +Color=red +Shape=circle +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>/etc/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>TDEHOME</envar></seg> +<seg><filename class="directory">~/.trinity</filename></seg> +<seg></seg> +</seglistitem> + +<seglistitem> +<seg><envar>TDEROOTHOME</envar></seg> +<seg><filename class="directory">/root/.trinity</filename></seg> +<seg>Different variable to prevent +root writing to $TDEHOME of the user after running +<command>su</command>.</seg> +</seglistitem> + +<seglistitem> +<seg><envar>TDEDIR</envar></seg> +<seg><filename class="directory">/opt/trinity</filename>, <filename +class="directory">/usr</filename>, <filename +class="directory">/usr/trinity</filename></seg> +<seg>Vendor dependent. If not set, falls back to +compiled-in default.</seg> +</seglistitem> + +<seglistitem> +<seg><envar>TDEDIRS</envar></seg> +<seg><filename class="directory">/opt/trinity</filename>, <filename +class="directory">/usr</filename>, <filename +class="directory">/usr/trinity</filename></seg> +<seg>Can list multiple locations separated by a +colon. If not set, falls back to $<envar>TDEDIR</envar></seg> +</seglistitem> + +</segmentedlist> +</para> +<para>Don't <emphasis>need</emphasis> to be set, defaults work just fine.</para> + +<informalexample> +<para>A staff member at a university could have the following +settings:</para> +<programlisting> +TDEHOME='~/.trinity' +TDEROOTHOME='/root/.trinity' +TDEDIRS='/opt/tde_staff:/opt/trinity' +</programlisting> + +</informalexample> + +</sect1> + +<sect1 id="user-profiles"> +<title>User Profiles</title> + +<para>In the previous example <filename +class="directory">/opt/tde_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/tderc</filename>:</para> + +<programlisting> +[Directories-staff] +prefixes=/opt/tde_staff +</programlisting> + +<para>This creates a profile named <quote>staff</quote> that adds the +<filename class="directory">/opt/tde_staff</filename> directory +tree. 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/tderc</filename>:</para> + +<programlisting> +[Directories] +userProfileMapFile=/etc/tde-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/tde-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 &tde; 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>TDEHOME</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 &tde; executables.</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">lib</filename></term> +<listitem><para>Used for &tde; 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 &tde; 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 +&tde;-menu (legacy)</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/applications</filename></term> +<listitem><para><literal role="extension">.desktop</literal> files for +&tde;-menu</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 &tde; 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>TDEHOME</envar></filename>. At the end of a +session &tde; 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/tde/HTML</filename></term> +<listitem><para>This directory contains documentation for &tde; +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. &tde; 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 &tde; 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>TDEHOME</envar>/socket-$<envar>HOSTNAME</envar></filename></term> +<listitem><para>Usually <filename +class="directory">/tmp/tdesocket-$<envar>USER</envar>/</filename>, this +is used for various &UNIX; sockets.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>$<envar>TDEHOME</envar>/tmp-$<envar>HOSTNAME</envar></filename></term> +<listitem><para>Usually <filename +class="directory">/tmp/tde-$<envar>USER</envar>/</filename>, this is used for temporary files.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>$<envar>TDEHOME</envar>/cache-$<envar>HOSTNAME</envar></filename></term> +<listitem><para>Usually <filename +class="directory">/var/tmp/tdecache-$<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>&tde; uses a simple +text-based file format for all its configuration files. It consists of +key-value pairs that are placed in groups. All &tde; 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> +[TDE] +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 &tde; +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 &tde; 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>TDEHOME</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>/.trinity/share/config/foobar</filename> +contains: +<programlisting> +[MyGroup] +Color=red +Shape=circle +</programlisting> +and <filename>/etc/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>/.trinity/share/config/foobar</filename> + contains +<programlisting> +[MyGroup] +Color=red +Shape=circle +[MyGroup] +Color=green +</programlisting> +and <filename>/opt/tde_staff/share/config/foobar</filename> contains +<programlisting> +[MyGroup] +Color=purple +Position=20,20 +</programlisting> +and <filename>/etc/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 <emphasis>immutable</emphasis>. 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>/.trinity/share/config/foobar</filename> + contains: +<programlisting> +[MyGroup] +Color=red +Shape=circle +</programlisting> +and <filename>/etc/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>/.trinity/share/config/foobar</filename> + contains: +<programlisting> +[MyGroup] +Color=red +Shape=circle +</programlisting> +and <filename>/opt/tde_staff/share/config/foobar</filename> contains +<programlisting> +[MyGroup] +Color=purple +Shape=rectangle +</programlisting> +and <filename>/etc/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. In <filename class="directory">$<envar>TDEDIR</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 &tde; 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="tde-startup-sequence"> +<title>&tde; Startup Sequence</title> + +<sect2 id="tdm"> +<title>&tdm;</title> + +<para>&tdm; always runs as <systemitem class="username">root</systemitem>. &tdm; uses +<filename>$<envar>TDEDIR</envar>/share/config/tdmrc</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>tdmrc</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 TDE session: <command>tde</command> or <command>starttde</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="starttde"> +<title>The &tde; Startup Script: <command>starttde</command></title> + +<para>The &tde; startup sequence starts with the +<filename>starttde</filename> script. In most cases this script gets called +from the display manager (&tdm;) once the user has been authenticated. Their +are two important lines in the <filename>starttde</filename> +script:</para> + +<programlisting> +LD_BIND_NOW=true $TDEDIR/bin/start_tdeinit_wrapper --new-startup +kcminit_startup +$TDEDIR/bin/tdeinit_phase1 +</programlisting> + +<para>The first line starts the <command>tdeinit</command> master process. +The <command>tdeinit</command> master process is used to start all other +&tde; processes. It shows up in the output of <command>ps +<option>aux</option></command> as <computeroutput>tdeinit: +Running...</computeroutput>. The arguments after <command>tdeinit</command> +are the names of additional processes to be started. The <token>+</token> +indicates that <command>tdeinit</command> needs to wait till the process has +finished. <command>tdeinit</command> also starts +<command>dcopserver</command>, <command>tdelauncher</command> and +<command>kded</command>.</para> + +<para>The second of the two lines asks <command>tdeinit</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 &tde; 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="tdesycoca">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>tdelauncher</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="tdelauncher"/> 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="tdeinit"> +<title><command>tdeinit</command></title> +<para><command>tdeinit</command> is used to start all other &tde; +programs. <command>tdeinit</command> can start normal binary program files +as well as <command>tdeinit</command> loadable modules. Loadable modules +work just like binary program files but can be started more efficiently. +Loadable modules live in <filename +class="directory">$<envar>TDEDIR</envar>/lib/trinity</filename></para> + +<para>The drawback is that programs started this way appear as +<computeroutput><command>tdeinit</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 tdeinit: Running... +waba 23187 0.1 2.1 23200 11124 ? S 21:41 0:00 tdeinit: dcopserver --nosid +waba 23189 0.2 2.4 25136 12496 ? S 21:41 0:00 tdeinit: tdelauncher +waba 23192 0.7 2.8 25596 14772 ? S 21:41 0:00 tdeinit: kded +waba 23203 0.8 3.4 31516 17892 ? S 21:41 0:00 tdeinit: +knotify +</computeroutput> +</screen> + +<para><computeroutput>tdeinit: Running...</computeroutput> indicates the +master <command>tdeinit</command> process. The other processes listed are +programs started as loadable modules.</para> + +<para>When <command>tdeinit</command> starts for the first time it will +launch <command>dcopserver</command>, <command>tdelauncher</command>, and +<command>kded</command>, as well as any additional programs specified on its +command line in the <command>starttde</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 &tde; applications. The &DCOP; +facilities are accessible from the command shell via the +<command>dcop</command> command line tool. &DCOP; is essential for all &tde; +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-TDE-Init</varname> line:</para> + +<programlisting> +[Desktop Entry] +Encoding=UTF-8 +Exec=tdecmshell energy +Icon=energy_star +Type=Application +X-TDE-Library=energy +X-TDE-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="tdelauncher"> +<title><command>tdelauncher</command></title> + +<para><command>tdelauncher</command> is a daemon which is responsible for +service activation within &tde;. It operates in close connection with the +<command>tdeinit</command> master process to start new processes. &tde; +applications communicate with <command>tdelauncher</command> over &DCOP; in +order to start new applications or services.</para> + +<para>Best known from the error message: <computeroutput><errortext> +TDELauncher could not be reached via DCOP </errortext></computeroutput> which +either indicates a serious problem with the <command>dcopserver</command> or +that <command>tdelauncher</command> crashed.</para> + +<para><command>tdelauncher</command> can be restarted by restarting +<command>tdeinit</command> from a console window. Make sure that +$<envar>HOME</envar>, $<envar>DISPLAY</envar> and the various +$<envar>TDEDIR(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 &tde;'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>TDEDIR</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-TDE-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-TDE-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 &tde; desktop</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>&kicker;</command></term> +<listitem><para>The &tde; 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><command>&klipper;</command></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>TDEHOME</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 &tde; 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>TDEHOME</envar>/share/config/session</filename>. +The state information of &twin; 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 &tde;:</para> + +<variablelist> + +<varlistentry> +<term>$<envar>TDEDIR</envar></term> +<listitem><para>Has to be set if +<envar>TDEDIRS</envar> is not set and has to point to the root of the +&tde; installation tree. Allows &tde; to find its data like icons, +menus and libraries.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDEDIRS</envar></term> +<listitem><para>Overrides <envar>TDEDIR</envar> and allows you to specify +multiple directories where &tde; searches for its data. Useful if you want +or have to install some programs to a different prefix than the rest of +&tde;.</para> +</listitem> +</varlistentry> + +<varlistentry><term><envar>$TDEHOME</envar></term><listitem><para>If +not set, &tde; uses <filename class="directory">~/.trinity</filename> as +the directory where personal data is stored.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDEROOTHOME</envar></term><listitem><para>If +not set, &tde; uses <filename class="directory">~root/.trinity</filename> +as the directory for <systemitem class="username">root</systemitem>'s +personal data. Was introduced to prevent &tde; from accidently +overwriting user data with root permissions when the user runs a &tde; +program after switching with <command>su</command> to <systemitem +class="username">root</systemitem>.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDEWM</envar></term><listitem><para>If the +<envar>TDEWM</envar> environment variable has been set, then it will +be used as &tde;'s window manager within the +<command>starttde</command> script instead of &twin;.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDE_LANG</envar></term><listitem><para>Overrides +the &tde; language configuration, ⪚ <userinput>TDE_LANG=fr kprogram +&</userinput> starts a program with French translation if the +necessary files are installed.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDE_MULTIHEAD</envar></term><listitem><para>Set +this variable to <literal>true</literal> to indicate that &tde; is running +on a multi-head system.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDE_FORK_SLAVES</envar></term> +<listitem><para>Set this variable to spawn +<acronym>TDEIO</acronym>-slaves directly from the application process +itself. By default <acronym>TDEIO</acronym>-slaves are spawned using +<command>tdelauncher</command>/<command>tdeinit</command>. This option is +useful if the <acronym>TDEIO</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>TDE_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>TDE_NO_IPV6</envar></term><listitem><para> +Set this variable to disable <acronym>IPv6</acronym> +support and <acronym>IPv6</acronym> <acronym>DNS</acronym> +lookups.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDE_IS_PRELINKED</envar></term><listitem><para> +Set this variable to indicate that you have prelinked +your &tde; binaries and libraries. This will turn off +<command>tdeinit</command>.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDE_UTF8_FILENAMES</envar></term><listitem><para>If +this environment variable is set, &tde; 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> +Automatically set to true by &tde; 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 (⪚ &tdesu; does that, it's also useful for +debugging).</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDESYCOCA</envar></term><listitem><para>Allows +you to specify the path and the name of the generated &tde; system +configuration cache file.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDETMP</envar></term><listitem><para>Allows +to specify another path than <filename +class="directory">/tmp</filename> where &tde; stores its temporary +files.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>TDEVARTMP</envar></term><listitem><para>Allows +to specify another path than <filename +class="directory">/var/tmp</filename> where &tde; stores its variable +files.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>XDG_DATA_HOME</envar></term><listitem><para> +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> +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>&tde; adds locations from $<envar>TDEDIRS</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> + - 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> +- 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> &tde; adds locations from +$<envar>TDEDIRS</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-tdeinit-mystery"> +<title>The tdeinit Mystery</title> + +<!-- FIXME: Add more words. Fix markup --> + +<para><command>tdeinit</command> is used to start all other &tde; +programs. <command>tdeinit</command> can start normal binary program f iles +as well as <command>tdeinit</command> loadable modules. Loadable modules work just like binary +program files but can be started more efficiently. Loadable modules +live in <filename +class="directory">$<envar>TDEDIR</envar>/lib/trinity</filename></para> + +<para>The drawback is that programs started this way appear as +<computeroutput><command>tdeinit</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 tdeinit: Running... +bastian 26064 0.0 2.2 24036 11524 ? S 21:27 0:00 tdeinit: dcopserver +bastian 26066 0.1 2.5 26056 12988 ? S 21:27 0:00 tdeinit: tdelauncher +bastian 26069 0.4 3.2 27356 16744 ? S 21:27 0:00 tdeinit: kded +bastian 26161 0.2 2.7 25344 14096 ? S 21:27 0:00 tdeinit: ksmserver +bastian 26179 1.1 3.4 29716 17812 ? S 21:27 0:00 tdeinit: kicker +bastian 26192 0.4 3.0 26776 15452 ? S 21:27 0:00 tdeinit: klipper +bastian 26195 1.0 3.5 29200 18368 ? S 21:27 0:00 tdeinit: 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 +tdeinit</command></userinput>, but killing all tdeinit processes will have +the effect of shutting down all of &tde;. In effect, total +destruction!</para> + +<para>There are two simple solutions to this:</para> + +<screen><prompt>%</prompt> <userinput><command>tdekillall kdesktop</command></userinput> +or good old +<prompt>%</prompt> <userinput><command>kill 26195</command></userinput></screen> +<para><command>tdekillall</command> is part of the &tde; <acronym>SDK</acronym> +package.</para> + +</sect1> + +</chapter> + +<chapter id="customizing-tde"> +<title>Customizing &tde;</title> + + +<sect1 id="desktop-icons"> +<title>Desktop Icons</title> + +<para>&tde; 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</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.trinitydesktop.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 &tde; 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-TDE-StartupNotify=true<co id="co-x-tde-startupnotify"/> +X-DCOP-ServiceType=Multi<co id="co-x-dcop-servicetype"/> +Categories=Qt;TDE;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-tde-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 &tde; 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 &tde;.</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; &tde; 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; &tde; +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>TDEDIR</envar>/share/apps/kdesktop/Desktop</filename> +(merged)</para></listitem> + +<listitem><para><filename +class="directory">$<envar>TDEDIR</envar>/share/apps/kdesktop/DesktopLinks</filename> +(copied)</para></listitem> + +<listitem><para>Device Icons (dynamically +merged)</para></listitem> + +<listitem><para>Distribution Specific</para></listitem> + +</itemizedlist> +</para> +</sect2> +</sect1> + +<sect1 id="tde-menu"> +<title>&tde; Menu</title> + +<sect2 id="how-it-works"> +<title>How it Works</title> + +<para>A common menu format is used as defined at +<ulink +url="http://freedesktop.org/Standards/menu-spec/">http://freedesktop.org/Standards/menu-spec/</ulink></para> + +<para>The 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 &tde;, &kde;, <acronym>GNOME</acronym>, and Xfce</para></listitem> +<listitem><para>Supports applnk style menus as well</para></listitem> +</itemizedlist> +</para> + +<informalexample> +<para>Example from <filename>tde-applications.menu</filename>: +<programlisting> +<markup> + <Menu> + <Name>Office</Name> + <Directory>suse-office.directory</Directory> + <Include> + <Filename>Acrobat Reader.desktop</Filename> + <Filename>tde-kpresenter.desktop</Filename> + <Filename>tde-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/tde/kpresenter.desktop</filename></para></listitem> + +<listitem><para><filename>/opt/trinity/share/applications/tde/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>TDEDIR</envar>/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>TDEDIR</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>TDEDIR</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>tde-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;TDE;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, &tde; 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">/etc/trinity/xdg/menus/applications-merged/</filename> +contains <filename>tde-essential.menu</filename> which includes some +essential menus that are normally not shown in the &tde; menu itself: +<itemizedlist> +<listitem><para>Control Center has a hidden Settings menu whose +contents are defined by <filename>tde-settings.menu</filename> and +whose icon and name are defined by <filename>tde-settings.directory</filename></para> +</listitem> +<listitem><para>Screensavers contains a hidden System/Screensavers menu, +whose contents are defined by +<filename>tde-screensavers.menu</filename> and whose icon and name +are defined by +<filename>tde-system-screensavers.directory</filename>. +<filename>$<envar>TDEDIR</envar>/share/desktop-directories/tde-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>&tde; continues to support old-style menus that are defined by +the directory structures in <filename +class="directory">$<envar>TDEDIR</envar>/share/applnk</filename> +(system wide) and <filename +class="directory">$<envar>HOME</envar>/.trinity/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="tdesycoca"> +<title><application>TDESycoca</application></title> +<para><application>TDESycoca</application> caches menu structure and +information about all available applications. You can rebuild the +database with +<userinput><command>tdebuildsycoca</command></userinput>. The database +which is built lives in <filename +class="directory">/var/tmp/tdecache-${<envar>USER</envar>}/tdesycoca</filename>. +It is automatically updated by <application>KDED</application>, +checked during &tde; 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>tdedrc</filename>: +<programlisting> +[General] +CheckSycoca=false +</programlisting> +</para> + +<para>To force regeneration, run <userinput><command>touch $<envar>TDEDIR</envar>/share/services/update_tdesycoca</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-tdemenuedit.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="tde-panel"> +<title>&tde; Panel</title> + +<para>The &tde; 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>&tde; 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 &tde; are stored in <filename +class="directory">$<envar>TDEDIR</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>/.trinity/share/config/profilerc</filename>. +To use the same settings for multiple users, store these settings in +user profile directory or the global &tde; config directory to use as +default for multiple users.</para> + +</informalexample> + +</sect1> + +</chapter> + +<chapter id="locking-down-tde"> +<title>Locking Down &tde;</title> + +<sect1 id="how-it-works-the-basics"> +<title>How It Works - The Basics</title> + +<para>&tde;'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 &tde;</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>&tde; 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>[TDE Action Restrictions] +shell_access=false</screen> + +<para>Since this affects the &tde; menu and the available applications, we +must force an update of the sycoca database:</para> + +<screen><userinput><command>touch</command> <filename>$<envar>TDEDIR</envar>/share/services/update_tdesycoca</filename></userinput></screen> + +<para>Now re-login to &tde; 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://techbase.kde.org/KDE_System_Administration/Kiosk/Keys"> +http://techbase.kde.org/KDE_System_Administration/Kiosk/Keys</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/Request Enhancement...</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 +&tdm;)</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>[TDE 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>[TDE 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 &tde; temporary directory of the +user, ⪚ <filename class="directory">/tmp/tde-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>[TDE 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 &tde; temporary directory of the user. This is needed by +certain &tde; 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>[TDE 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>TDEDIR</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>TDEDIR</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>&tde; has configuration modules to configure various aspects of the +&tde; 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>tdecmshell</command> <replaceable>module</replaceable></para> + +<para>To start the Proxy module use:</para> +<itemizedlist> +<listitem><para><command>tdecmshell</command> +<filename>tde-proxy.desktop</filename></para></listitem> +<listitem><para><command>tdecmshell</command> +<filename>tde-proxy</filename></para></listitem> +<listitem><para><command>tdecmshell</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 &tde; +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>TDEDIR</envar>/share/applications/tde</filename> +and are sorted under the hidden <guimenu>Settings-Modules</guimenu> menu by +the <filename>tde-settings.menu</filename>, included from +<filename>tde-essential.menu</filename></para> +<screen><userinput><command>tdebuildsycoca</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>TDEDIR</envar>/share/applnk/.hidden</filename> which +corresponds to the hidden .hidden menu, included as a result of +<markup><KDELegacyDirs/></markup></para> +<screen><userinput><command>tdebuildsycoca</command> <option>--menutest</option> 2> /dev/null | <command>grep</command> .hidden</userinput></screen> +</listitem> +<listitem><para>It is possible to edit the Control Center with +<application>kcontroledit</application>. +<application>kcontroledit</application> works 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 disabled by adding the +following to <filename>kdeglobals</filename>:</para> + +<screen>[TDE Control Module Restrictions] +<replaceable>module-id</replaceable>=false</screen> +<para>For example, to disable the proxy module use</para> +<screen>[TDE Control Module Restrictions] +tde-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> + +</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 &tde; 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 &tde; applications from the command line +KDialog + A versatile tool to use standard &tde; dialogs in your own scripts + + + +Deployment +Thin Clients +Installing Software += AutoYaST += KickStart +Maintaining Settings += /etc/tderc, 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; (&tde; remote +frame buffer, a VNC server) and &krdc; (&tde; 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="tde-diy"> +<title>&tde; 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. +&tde; 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/tdefile/bookmarks.xml +KBookmarkManager-.../share/apps/konqueror/bookmarks.xml +KBookmarkNotifier +KDebug +MainApplication-Interface +konsole (default) +konsole-mainwindow#1 +tdesycoca +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>&tde; DIY - Building Your Own Tools</subtitle> + +<para>You can use &tde; dialogs from your own scripts, to combine the power +of &UNIX; shell scripting with the ease of use of &tde;.</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>TDEHOME</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; + +</book> |