From 66c5602f5818d46f618b4dacaaf8bdc00cfacdd2 Mon Sep 17 00:00:00 2001 From: Darrell Anderson Date: Fri, 31 Jan 2014 14:03:54 -0600 Subject: Move Administrator Guide from User Guide to standalone handbook. --- doc/adminguide/CMakeLists.txt | 9 + doc/adminguide/Makefile.am | 3 + doc/adminguide/groupware-kontact.docbook | 614 +++++++ doc/adminguide/index.docbook | 2772 ++++++++++++++++++++++++++++++ 4 files changed, 3398 insertions(+) create mode 100644 doc/adminguide/CMakeLists.txt create mode 100644 doc/adminguide/Makefile.am create mode 100644 doc/adminguide/groupware-kontact.docbook create mode 100644 doc/adminguide/index.docbook (limited to 'doc/adminguide') diff --git a/doc/adminguide/CMakeLists.txt b/doc/adminguide/CMakeLists.txt new file mode 100644 index 000000000..ec8d87dac --- /dev/null +++ b/doc/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/adminguide/Makefile.am b/doc/adminguide/Makefile.am new file mode 100644 index 000000000..86108a74b --- /dev/null +++ b/doc/adminguide/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = khelpcenter/adminguide + diff --git a/doc/adminguide/groupware-kontact.docbook b/doc/adminguide/groupware-kontact.docbook new file mode 100644 index 000000000..b18313931 --- /dev/null +++ b/doc/adminguide/groupware-kontact.docbook @@ -0,0 +1,614 @@ + + + + + + +Marco +Menardi + +gnu@kde.org + + + + + + +Sharing data with &kontact; via <acronym>IMAP</acronym> + + +Introduction + +For my small office, I was looking for a long time for a +PIM 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 +Kolab server 1.0 (the server side of the +project), I gave up, waiting for an easier to deploy +Kolab 2.0. In any case, the +Kolab stuff was clearly too much for my +needs. Fortunately in the &tde; wiki I've found some piece of +IRC conversation where they were talking about sharing +data without the Kolab infrastructure... mmm so +interesting! + +For small offices and needs, you can have &kontact; use shared data +without the need of installing the Kolab server +or another groupware backend. It can work with just an +IMAP server, that can be easily set up. + +My scenario is a server with Debian unstable and &tde; 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. + + + + +What is <acronym>IMAP</acronym> + +This definition is from the ComputerUser.com High-Tech Dictionary: +
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.
 + +So it can be considered a data storage. To use it you you need an +IMAP server, such as Cyrus, +Courier or UW. + + + + +<application>Kolab</application> or <acronym>IMAP</acronym>? + +Kolab brings the ability to share data +between different clients. It makes possible for your secretary to use +Outlook and you use &kontact;, for +instance. + +You will have a configuration interface which does user management, mail +account setup, a central LDAP 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; + +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 +IMAP. + + + + +How to set up <acronym>IMAP</acronym> server <application>Cyrus</application> + +My choice is Cyrus, that is part of the +Kolab set of software, so if l will go for +Kolab in the future, at least I'm acquainted with +it. Let's start the installation and the setup! + +Become root. + +# apt-get install cyrus21-imapd cyrus21-common cyrus21-admin cyrus21-client sasl-bin sasl2-bin +Installing cyrus21-imapd...The installer asks something I've not understood about an search address... I just pressed Enter. + +The installer also created the user cyrus that is in the (automatically created) +group sasl, that is the +owner of all cyrus files. At the end with ps + you can find the new processes: +cyrmaster and notifyd. + +The real problem in setting up Cyrus is the +authentication, just because it's not trivial and I'm a newbie, with limited +knowledge about what I'm doing. + +Cyrus can use different +SASL (Simple Authentication and Security Layer) +mechanisms, the default being sasldb (it stores usernames and passwords in +the SASL secrets file sasldb), but also getpwent, +kerberos4, kerberos5, PAM, rimap, shadow and LDAP are supported. + + Since I don't want to define users/passwords different than the ones +that access my &Linux; box I choose then shadow mechanism so +Cyrus will use &Linux; passwords for +authenticate. + +To do so we have to tell sasl to use saslauthd as +password authentication method, and then setup saslauthd +to use shadow (or getpwent) as the +authentication mechanism. + +OK, let's start! + +As root, change the Linux +password of cyrus user: + +# passwd + +Enter the password you like (and you will remember) we will use for +this example cyrus as the cyrus +administrator password. + +# vi /etc/imapd.conf + +sasl_pwcheck_method: saslauthd instead of the default auxprop + +remove the # remark from the line: + +#admins: cyrus + +this way you can administer cyrus logging +in as cyrus user (what a fantasy I +have!) + +# vi /etc/default/saslauthd + +Uncomment the line: + +# START=yes + +(otherwise the saslauthd will not start at +boot time, even if referenced in some /etc/rcx.d!) + +and instead of MECHANISMS="pam" put +MECHANISMS="shadow" this way at the boot a +saslauthd will be executed. + +Once exited from your editor, restart sasl +and cyrus. + +To test IMAP: + + su +$ imtest + +You are prompted for the cyrus (user) password, so enter it. + +If the user cyrus is +correctly authenticated, the following lines will appear: + +S: L01 OK User logged in +Authenticated. +To exit type . logout (&ie; dot space logout) + +Now add a user named groupware and set a password for it, using +your usual system tools. It should be in an unprivileged group such as +nobody and does not require a +login shell or a home directory. + +Now I have to create the user and an IMAP in +cyrus also: + +# cyradm +after entering the password for the admin user cyrus, you get the prompt localhost> +localhost> cm +localhost> lm lists the mailbox only just created +user.groupware (\HasNoChildren)) +localhost> quit + +You can type help for a list +of available commands. + +You can check what has happened with: + +# ls /var/spool/cyrus/mail/g/user/groupware +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 + +Now you should be able to connect with an IMAP client +as the groupware user and see the +INBOX. +In the IMAP protocol, selecting the mailbox +INBOX is a magic word, a sort of alias for +the above directory structure. The client sees INBOX, and +the IMAP server maps it in the /var/spool/cyrus/mail/... folder and file +structure. + + + + +How to setup &kontact; clients + +I connect to my GNU/Linux office server PC (a sort of "black box" +without monitor and keyboard) from 2 &Windows; 2000 PC with +Cygwin/X, 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 +Cyrus is installed and running +(localhost). + +To have &kontact; work with IMAP, there are these +steps to complete: + + + +Create an IMAP account on the +Cyrus for fake groupware user (already previously +done!) + +Create/configure an IMAP account in &kmail; +for login as that user Use tderesources to make +&kontact; components work with data taken from IMAP +source + +Enable groupware functionality and make related subfolders of +that IMAP INBOX (if not +already) + +Enjoy &kontact; and shared data through +Cyrus IMAP + + + +So login to &tde; with the first real user account you +want to provide groupware functionality to. + +Let's create the IMAP account in &kmail;. + +Run &kontact; and select Mail (the &kmail; +component). From the menu choose +SettingsConfigure KMail +AccountsReceiving tab, press the Add... button. You will then be +prompted for the type of your email account, and select +disconnected IMAP (not just +IMAP). Then in the General tab +enter the following data: + + + +Account Name: office_gwdata + +A name that will be used for the local folder that +points to this IMAP account. + + + +Login: groupware + +The Cyrus user we have chosen as +owner of all of the office data + + +Password: + +The password of the groupware user. + + + +Host: localhost + +Remember for our example, the &kontact; client runs on the same +computer as the IMAP server + + + +Port: 143 + +The default + + + + +Check store IMAP password +so you will not be asked for it next time you run &kontact;. Check the +Enable interval mail checking and set a value in +minutes. + +Note that we have checked the disconnected IMAP +type account. This has the effect that a copy of the groupware data is +stored locally 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 +disconnected IMAP data is cached locally, and only the +delta (&ie; the data that has changed) is sent. + +On the other end, if your users run &korganizer; on the same PC that +runs the IMAP server, it seems reasonable to use +IMAP (that is called online IMAP) to save +space, since transfer speed should not be an issue. But unfortunately this +does not work because &kontact; does not update automatically the +Calendar folder in online IMAP, so you +are not updated when someone adds events (you must manually switch to +&kmail; application and click on the Calendar +folder). In addition, at start up when it does read +Calendar folders, you may see a tremendous flicker and +slow data updates. + +Now we have to tell &kontact; to use IMAP as the +data source for it's various components. From the &kmenu;, choose +Run command, run tdecmshell +tderesources. In the combo box select +Contacts, then press the Add... +button, and choose Addressbook on IMAP Server via KMail. Then select that new line and +press Use as Standard button. Do the same for +Calendar and Notes. + +Now we have to enable the &kmail; (and as a consequence, the whole +&kontact;) groupware functionality: + + + +Choose from the menu +SettingsConfigure +KMailMiscGroupware + + +Check Enable IMAP resource functionality + + +Choose English as Language of the +groupware folders (this is in case you already have the folders +in the IMAP server created by a different program in a +different language). + + +Now move to Resource folder are in account and +select the the Inbox subfolder of the +office_gwdata folder. +Leave Hide groupware folders unchecked for now, +so we can see that happens. You can return here and check it once everything +is clear. + + +When you press OK you are prompted with: +&kmail; will now create the required folders for the IMAP +resource as subfolders of Inbox +If you do not want this, press No, and the +IMAP resource will be disabled. Press +Yes (this happens only the first time with the first +real user). You will immediately see that in the &kmail; +folder tree, under +office_gwdataInbox +these subfolders are created: + +Calendar +Contacts +Notes +Tasks +Journal + +if you now do a: +# ls +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 + +As you see, the office_gwdata Inbox is stored not +local to the &kontact; current user home, but in the IMAP +groupware user's folders. + + + +Now &kontact; is ready to work and store data there. In the calendar +application, if &kmail; IMAP account was of type +disconnected, the resource window should +display the item Imap resource with 3 subitems, that +are paths to local home files. Instead, the Contacts +application does not show subitems below the Imap +resource. + +You can now login to &tde; with a different username and set up +his/her &kontact; client in a very similar manner: + + + +Open &kontact; and in the Mail component add an +IMAP account specifying as host the +computer where Cyrus server runs (in my case: +192.168.1.3). + +Remember to check the Enable interval mail +checking and set a value in minutes. When you confirm, you are +not prompted for the subfolder creation (since they are found in the +IMAP server), and you see them in the folder tree. + + +Activate the groupware functionality to be able to save data in the +IMAP server. + + +Beware that in disconnected IMAP, +data are transmitted from a client to IMAP server only +when the clients connects to check for new mail. So if you have your +&kontact; clients with an interval mail checking 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. + + +How to have Read Only Access + +Beware that I've been confirmed that Notes +IMAP 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. + +In the previous setup, we have the same fake user, named +groupware, that is used by all the +real &kontact; users (&ie; tony, rohn, amanda, &etc;) through the +IMAP 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 groupware to the IMAP +server. + +To limit access to some users (typically, providing read-only access), +we can use the ACL (Access Control Lists). + +Select in &kmail; a subfolder of office_gwdata +inbox, for instance Calendar, and right click the +mouse. Select PropertiesAccess +Control tab. Here you can enter the users you want give access to +this folder and what they can do. + +Just to experiment trying to exchange events, we give +All permission to the user mary + +At cyrus level (in the +PC that runs IMAP server cyrus, with +cyrus tools), we first need to add the user +mary, so it's an +IMAP recognized user, and create an +IMAP folder for her. + +Then we login to GNU/Linux as mary and enter &kontact;. As previously shown, +we will setup an IMAP account in &kmail; with the same +data but the one of the user (instead of the fake user groupware and it's password, we will use +mary and her password). + +In &kmail; folder tree, this time you will see this structure: +office_gwdatauser +groupwareCalendar and +Tasks. Check the mail +(FileCheck +Mail) and you will also have an +inbox folder under office_gwdata. + +Now enable &kmail; groupware functionality, and in Resource +folders are subfolders of put the +inbox that is subfolder of +office_gwdata. + +Now enable &kmail; groupware functionality, and in Resource +folders are subfolders of put the +inbox that is subfolder of +office_gwdata. + +Now you have two branches of folder under +office_gwdata: + + + +inbox with Calendar, Contacts, Notes, Tasks and +Journal, that are saved on mary +IMAP folders on the IMAP server + + +user, with the subfolder groupware and +the subfolders to which mary has +access to (in this example, Calendar and Tasks) + + +&RMB; click on the user Calendar and +check if it's of type Calendar (if not, set it to be), and also if +userTasks is of type Tasks. +Now in Calendar you have two available IMAP +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!). +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 +.groupware.directory path (see the tail part of each +resource path). + + + + +Credits + +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. + + +Special thanks to: + +For the Cyrus IMAP part +in #cyrus channel: + + +[protagonist] Andy Morgan morgan@orst.edu + + +[plixed] Okke Timm okke.timm@web.de + + + + +For the &kontact; part in #kontact channel: + + +[till] Till Adam adam@kde.org + + +[dfaure] David Faure faure@kde.org + + +[mdouhan] Matt Douhan matt@fruitsalad.org + + + + + +Thank a lot guys! + +Ah, and there is also me, [markit] Marco Menardi +mmenaz@mail.com + + + + +Further Reading + + +Reference +KDE: http://www.kde.org +&kontact; website: http://www.kontact.org +Kroupware project: http://www.kroupware.org +&kde; Community Wiki: http://wiki.kde.org +Wine project: http://www.winehq.org +Cygwin/X project http://x.cygwin.com +LTSP project: http://www.ltsp.org + + + + + + + diff --git a/doc/adminguide/index.docbook b/doc/adminguide/index.docbook new file mode 100644 index 000000000..9b767ec4a --- /dev/null +++ b/doc/adminguide/index.docbook @@ -0,0 +1,2772 @@ + + + + + +]> + + + + + +The &tde; (Trinity Desktop Environment) Administrator Guide + + +&tde-team; + + + + +2004-2005 +The &kde; Team + + +&tde-copyright-date; +&tde-team; + + + + +&tde-release-date; +&tde-release-version; + + +A general administrator guide to the Trinity Desktop Environment. + + +Please report problems with this document to +trinity-devel@lists.pearsoncomputing.net. + + + + +KDE +TDE +desktop +handbook +tutorial + + + + + +&tde; for Administrators + + +Overview + +This handbook is a reference guide to +some &tde; features that are useful to administrators configuring +multi-user systems. This part also has information that might be 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 which allows administrators to limit +what users can do in &tde;. That framework is potentially useful in many +situations, but especially for running single-function kiosks with, +for example, only a web browser, hence the name. + + + + +Directory Layout + +&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. + + +By default &tde; uses two directory trees: + + +One at the system level (for example /opt/trinity). +One at the user level in the user's home directory +(usually +~/.trinity) + + +As a system administrator you can create additional trees. Such +additional trees can be used for profiles + +&SuSE; &Linux; for example uses: + + +$HOME/.trinity +/opt/trinity. (This is +&SuSE;-specific; other distributions may use +/usr or /usr/trinity) +/etc/opt/trinity. (This was added by +&SuSE;). + + +If you have the KIOSK Admin tool v0.7 or later installed you can +check which directory trees are used with the following command: +kiosktool-tdedirs + + + +&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. + + +For information about the text/plain &MIME; type +the following files are searched: + + +$HOME/.trinity/share/mimelnk/text/plain.desktop +/opt/trinity/share/mimelnk/text/plain.desktop +/etc/opt/trinity/share/mimelnk/text/plain.desktop + + +If a user makes a change, the change is written to $HOME/.trinity/share/mimelnk/text/plain.desktop + + +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. + + +For example, if the following two files exist, with these contents: + +$HOME/.trinity/share/config/foobar + +Color=red +Shape=circle + + + + + +/etc/opt/trinity/share/config/foobar + +Color=blue +Position=10,10 + + + + + +The files will be merged to result in: + + +Color=red +Shape=circle +Position=10,10 + + + + + + +Specifying Directories + + + + +Environment Variable +Example Setting(s) +Comment + + +TDEHOME +~/.trinity + + + + +TDEROOTHOME +/root/.trinity +Different variable to prevent +root writing to $TDEHOME of the user after running +su. + + + +TDEDIR +/opt/trinity, /usr, /usr/trinity +Vendor dependent. Used by &tde; 2. If not set, falls back to +compiled-in default. + + + +TDEDIRS +/opt/trinity, /usr, /usr/trinity +New in &tde;3. Can list multiple locations separated by a +colon. If not set, falls back to $TDEDIR + + + + +Don't need to be set, defaults work just fine. +Running &tde;2 next to &tde;3? Point $TDEDIR to +&tde; 2 and $TDEDIRS to &tde; 3. + + +A staff member at a university could have the following +settings: + +TDEHOME='~/.trinity' +TDEROOTHOME='/root/.trinity' +TDEDIRS='/opt/kde_staff:/opt/trinity' + + + + + + + +User Profiles + +In the previous example /opt/kde_staff contained additional settings +and applications for staff members. User Profiles allow you +to add this directory only for certain users and not for others. Add the +following to /etc/tderc: + + +[Directories-staff] +prefixes=/opt/kde_staff + + +This creates a profile named staff that adds the +/opt/kde_staff directory +tree. (Note that &SuSE; &Linux; uses +/etc/kde3rc instead of +/etc/tderc. Now that we have a named profile it +can be assigned to users. + +To map profiles to users a mapping file needs to be specified in +/etc/tderc: + + +[Directories] +userProfileMapFile=/etc/kde-user-profile + + +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. + +To assign the staff profile to all users that are a member of the +&UNIX; group staff_members add the following to +/etc/kde-user-profile: + + +[General] +groups=staff_members +[Groups] +staff_members=staff + + +It is also possible to assign a profile to a single user: + + +[Users] +bastian=staff + + + + + +Directory Layout Revisited + +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 $TDEHOME but not in any other +directory tree. + + + + +Architecture-specific Directories + +Architecture (OS and CPU type) specific directories: + + + +bin +Used for &tde; executables. + + + +lib +Used for &tde; libraries. + + + + +lib/trinity +This directory contains components, plugins, and other +runtime loadable objects for use by &tde; 3.x +applications. + + + + + + +Shared Directories + +Shared: Not architecture specific, can be shared between different +archs. + + + +share/applnk +.desktop files for +&tde;-menu (old) + + + +share/applications +.desktop files for +&tde;-menu + + + + +share/apps +Contains application-specific data files. Each +application has a sub-directory here for storing additional data +files. + + + +share/config +Configuration files. Configuration files are normally +named after the application they belong to plus the letters +rc. A special case is kdeglobals. +This file is read by all &tde; applications. + + + +share/config/session +This directory is used by session management and is +normally only available under $TDEHOME. 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 ksmserver stores references to +these numbers when saving a session in +ksmserverrc. + + + +share/doc/tde/HTML +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: index.docbook, which contains the +documentation in the unformatted DocBook format, and +index.cache.bz2, which contains the same +documentation formatted as bzip2-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. + + + + +share/icons +Under this directory icons are stored. Icons are +categorized by theme, dimension and usage category. + + + +share/mimelnk +In this directory,.desktop files that describe &MIME; types +are stored. &tde; uses &MIME; types to identify the type of a +file. + + + + +share/services +This directory contains .desktop 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. + + + + +share/servicetypes +This directory contains .desktop files that describe +servicetypes. A servicetype usually represents a certain programming +interface. Applications and Services include in their >.desktop files the servicetypes that they +provide. + + +share/sounds +This directory contains sound files. + + + +share/templates +This directory contains templates for creating files +of various types. A template consists of a .desktop file that describes the file and +that includes a reference to a file in the .source sub-directory. The templates in +this directory appear in the Create New menu +available on the desktop and in the file browser. When a user selects +a template from the menu its source file is copied. + + + + +share/wallpapers +This directory contains images that can be used as +background picture + + + + + + + +Host-specific Directories + +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 +lnusertemp utility: + + + + +$TDEHOME/socket-$HOSTNAME +Usually /tmp/tdesocket-$USER/, this +is used for various &UNIX; sockets. + + + + +$TDEHOME/tmp-$HOSTNAME +Usually /tmp/kde-$USER/, this is used for temporary files. + + + + +$TDEHOME/cache-$HOSTNAME +Usually /var/tmp/tdecache-$USER/, +this is used for cached files. + + + + +Since both /tmp and +/var/tmp 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 +lnusertemp utility will create a new directory with +an alternative name and link to that instead. + + + + +Configuration Files &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 UTF-8 encoding for text outside the +ASCII range. + +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. + +The following example shows a configuration +file that consists of two groups. The first group contains the keys +LargeCursor and SingleClick, the +second group contains the keys Show hidden files +and Sort by: + + +[TDE] +LargeCursor=false +SingleClick=true + + + +[KFileDialog Settings] +Show hidden files=false +Sort by=Name + + + +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: + + +entry=value + + +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 +s. + +There are several other backslash codes; here is a complete +list: + +\s can be used as space + +\t can be used to include a tab + +\r for a carriage return character + +\n for a linefeed character (new line) + +\\ to include the backslash itself + + + +In the following example the value of the +Caption entry starts with two spaces while the +Description entry contains three lines of +text. Linefeeds in backslash notation are used to separate the +different lines. + + +[Preview Image] +Caption=\s My Caption +Description=This is\na very long\ndescription. + + + +Empty lines in configuration files are ignored, as are lines that +start with a hash mark (#). 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 +not preserved. + +There can be multiple configuration files with the same name in the +share/config 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 $TDEHOME 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. + + +If $HOME/.trinity/share/config/foobar +contains: + +[MyGroup] +Color=red +Shape=circle + +and /etc/opt/trinity/share/config/foobar contains + +[MyGroup] +Color=blue +Position=10,10 + +the result will be: + +[MyGroup] +Color=red +Shape=circle +Position=10,10 + + + + + +If + $HOME/.trinity/share/config/foobar + contains + +[MyGroup] +Color=red +Shape=circle +[MyGroup] +Color=green + +and /opt/kde_staff/share/config/foobar contains + +[MyGroup] +Color=purple +Position=20,20 + +and /etc/opt/trinity/share/config/foobar contains + +[MyGroup] +Color=blue +Position=10,10 + +the result will be: + +[MyGroup] +Color=green +Shape=circle +Position=20,20 + + + + +To prevent users being able to override default settings, +settings can be marked immutable. Settings can be made immutable +individually, per group or per file. An individual entry can be locked +down by adding [$i] behind the key, ⪚: + +Color[$i]=blue + + +A group of entries can be locked down by placing +[$i] behind the group name, ⪚: + +[MyGroup][$i] + + +To lock down the entire file, start the file with +[$i] on a single line, &ie;: + +[$i] + + + + +If + $HOME/.trinity/share/config/foobar + contains: + +[MyGroup] +Color=red +Shape=circle + +and /etc/opt/trinity/share/config/foobar contains: + +[MyGroup][$i] +Color=blue +Position=10,10 + +the result will be: + +[MyGroup] +Color=blue +Position=10,10 + + + + +If + $HOME/.trinity/share/config/foobar + contains: + +[MyGroup] +Color=red +Shape=circle + +and /opt/kde_staff/share/config/foobar contains + +[MyGroup] +Color=purple +Shape=rectangle + +and /etc/opt/trinity/share/config/foobar contains + +[MyGroup][$i] +Color=blue +Position=10,10 + +the result will be + +[MyGroup] +Color=purple +Shape=rectangle +Position=10,10 + + + + + +So-called Shell Expansion 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 [$e]. 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 [$ie]. The user can't change it then of course. + + +In the following example the value for the Host +entry is determined by the output of the hostname +program. This setting is also locked down to ensure that the value is always +determined dynamically. + +The value for the Email entry is determined by +filling in the values of the $USER and $HOST +environment variables. When joe is +logged in on joes_host this will +result in a value equal to joe@joes_host. The setting is +not locked down. + + +[Mail Settings] +Host[$ie]=$(hostname) +Email[$e]=${USER}@${HOST} + + + +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. + + +In the following example the value of the Caption +entry depends on the language. If the user has selected French as language +(language code fr) the value of the entry will be +Ma Légende. In all other cases the value My +Caption will be used. + + +[Preview Image] +Caption=My Caption +Caption[fr]=Ma Légende + + + + +In this example the value of the Caption entry +depends on the language. If the user has selected French as language +(language code fr) the value of the entry will be +Ma Légende. In all other cases the value My +Caption will be used. + + +[Preview Image] +Caption=My Caption +Caption[fr]=Ma Légende + + + +In general the entries that can appear in a configuration file are not +documented. With &tde; 3.2 a start has been made to change this. In +$TDEDIR/share/config.kcfg, 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. + + +Here is an example &XML; configuration file: + + +<?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> + + + +It has the same effect as: + +[General] +Auto Save=false +Auto Save Interval=25 + + + + + + + +&tde; Startup Sequence + + +&tdm; + +Always runs as root! Uses +$TDEDIR/share/config/tdmrc and +/etc/X11/xdm/Xservers. The latter contains entries +like: + + +:0 local /usr/X11R6/bin/X :0 vt07 + + +Relevant startup files are also: + + +[X-*-Core] section in tdmrc + + +Setup - /etc/X11/xdm/Xsetup + + +User enters username & password + + +Startup - /etc/X11/xdm/Xstartup - prepare as root + + +Session - /etc/X11/xdm/Xsession - starts session as user + + += For a TDE session: kde or starttde + + += If present ~/.xsession or ~/.xinitrc + + +Reset - /etc/X11/xdm/Xreset - after session finished + + + + + + +The &tde; Startup Script: <command>starttde</command> + +The &tde; startup sequence starts with the +starttde script. In most cases this script gets called +from the display manager (&tdm;) once the user has been authenticated. Their +are two very important lines in the starttde +script: + + +LD_BIND_NOW=true tdeinit +kcminit +knotify and kwrapper +ksmserver $TDEWM + + +The first line starts the tdeinit master process. +The tdeinit master process is used to start all other +&tde; processes. It show up in the output of ps + as tdeinit: +Running.... The arguments after tdeinit +are the names of additional processes to be started. The + +indicates that tdeinit needs to wait till the process has +finished. tdeinit also starts +dcopserver, tdelauncher and +kded. + +The second of the two lines asks tdeinit to start +the ksmserver session manager process. The session +manager determines the lifetime of the session. When this process exits, the +user is logged out. + + + + + +Background Processes + +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: + + + +dcopserver +Desktop communication + + + + +kded +Generic service daemon. +Triggers Sycoca database updates when +needed + + + + +kcminit +Initialization service +See for more information. + + + + +tdelauncher +Program launch (this is not the +&Alt;F2 +dialog!) +See for more information. + + + + +knotify +User notifications. +See for more information. + + + + +ksmserver +Session management +See for more information. + + + + + + +<command>tdeinit</command> +tdeinit is used to start all other &tde; +programs. tdeinit can start normal binary program files +as well as tdeinit loadable modules +(KLMs). KLMs work just like binary +program files but can be started more efficiently. KLMs +live in $TDEDIR/lib/trinity + +The drawback is that programs started this way appear as +tdeinit in the output of +top and ps. Use top + or ps +to see the actual program name: + + +%ps + +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 + + + +tdeinit: Running... indicates the +master tdeinit process. The other processes listed are +programs started as KLMs. + +When tdeinit starts for the first time it will +launch dcopserver, tdelauncher, and +kded, as well as any additional programs specified on its +command line in the starttde script, normally +kcminit and knotify. + + + + +<command>dcopserver</command> + +dcopserver 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 +dcop command line tool. &DCOP; is essential for all &tde; +applications. + +Some related files: + + + +$HOME/.DCOPserver_$HOSTNAME_$DISPLAY +⪚ .DCOPserver_linux__0. Controlled by $DCOPAUTHORITY + + + + +/tmp/.ICE-unix/dcoppid-number +⪚ dcop7634-1069677856. This is +the file that the DCOPserver file above points to. + + + + +$HOME/.ICEauthority +Authorization information controlled by +$ICEAUTHORITY + + + + + + + +kcminit + +kcminit executes initialization services during +startup. Initialization services are specified in the .desktop files of +applications or services via the X-TDE-Init line: + + +[Desktop Entry] +Encoding=UTF-8 +Exec=tdecmshell energy +Icon=energy_star +Type=Application +X-TDE-Library=energy +X-TDE-Init=energy + + +Initialization services are typically used for initializing +hardware based on user-specified settings. + +kcminit + can be used to show all +initialization services and kcminit +service can be used to +execute a single service explicitly. This can be useful when investigating +startup problems. + + + + +<command>tdelauncher</command> + +tdelauncher is a daemon which is responsible for +service activation within &tde;. It operates in close connection with the +tdeinit master process to start new processes. &tde; +applications communicate with tdelauncher over &DCOP; in +order to start new applications or services. + +Best known from the error message: +TDELauncher could not be reached via DCOP which +either indicates a serious problem with the dcopserver or +that tdelauncher crashed. + +tdelauncher can be restarted by restarting +tdeinit from a console window. Make sure that +$HOME, $DISPLAY and the various +$TDEDIR(S) are set correctly when doing so! + + + + +<command>knotify</command> + +The primary task of knotify is to relay sound +notifications to the sound server, it also provides alternative notification +methods. + + + + + + + +KSMServer + +ksmserver 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 .desktop files in the +$TDEDIR/share/autostart +directory. Whether or not to auto-start an application can be made +conditional upon some configuration entry determined by the +X-TDE-autostart-condition entry in the .desktop file. + + +The ktip.desktop file for example +contains: + + +X-TDE-autostart-condition=ktiprc:TipOfDay:RunOnStart:true + + +This means that the ktiprc configuration +file is checked for a RunOnStart entry in the +[TipOfDay] section. If no such entry is found, +true is assumed, which means that +ktip is one of the applications that is +auto-started by default. + + +Some of the applications auto-started by ksmserver +are: + + + + +kdesktop +The &tde; desktop + + + + +&kicker; +The &tde; panel + + + + +ktip +A tip of the day program + + + + +kwrited +A utility to receive system messages sent to the user + + + + +&klipper; +A clipboard utility that docks in the panel + + + + +kalarm +A utility that warns about upcoming events and appointments + + + + + +kdesktop in its turn automatically starts +applications stored in $TDEHOME/Autostart. kdesktop +will automatically open any files stored in this directory including +documents, binary files or applications in the form of .desktop files. + +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 +ksmserverrc configuration file which contains +references to application-specific state information. The +application-specific state information is saved in $TDEHOME/share/config/session. +The state information of &twin; contains the location of the application +windows of all the other applications in the session. + + + + + +Environment variables + +Some important environment variables used by &tde;: + + + + +$TDEDIR +Has to be set if +TDEDIRS 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. + + + +$TDEDIRS +Overrides TDEDIR 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;. + + + +$TDEHOMEIf +not set, &tde; uses ~/.trinity as +the directory where personal data is stored. + + + +$TDEROOTHOMEIf +not set, &tde; uses ~root/.trinity +as the directory for root'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 su to root. + + + +$TDEWMIf the +TDEWM environment variable has been set, then it will +be used as &tde;'s window manager within the +starttde script instead of &twin;. + + + +$TDE_LANGOverrides +the &tde; language configuration, ⪚ TDE_LANG=fr kprogram +& starts a program with French translation if the +necessary files are installed. + + + +$TDE_MULTIHEADSet +this variable to true to indicate that &tde; is running +on a multi-head system. + + + +$TDE_FORK_SLAVES +Set this variable to spawn +TDEIO-slaves directly from the application process +itself. By default TDEIO-slaves are spawned using +tdelauncher/tdeinit. This option is +useful if the TDEIO-slave should run in the same +environment as the application. This can be the case with +Clearcase. + + + +$TDE_HOME_READONLY +Set this variable to indicate that your home directory is +mounted as read-only. + + + +$TDE_NO_IPV6 +Set this variable to disable IPv6 +support and IPv6 DNS +lookups. + + + +$TDE_IS_PRELINKED +Set this variable to indicate that you have prelinked +your &tde; binaries and libraries. This will turn off +tdeinit. + + + +$TDE_UTF8_FILENAMESIf +this environment variable is set, &tde; assumes all filenames are in +UTF-8 encoding regardless of the current C +locale. + + + +$TDE_FULL_SESSION +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). + + + +$TDESYCOCAAllows +you to specify the path and the name of the generated &tde; system +configuration cache file. + + + +$TDETMPAllows +to specify another path than /tmp where &tde; stores its temporary +files. + + + +$TDEVARTMPAllows +to specify another path than /var/tmp where &tde; stores its variable +files. + + + +$XDG_DATA_HOME +Defines the base directory relative to which user-specific +data files should be stored. Default is $HOME/.local/share + + + +$XDG_DATA_DIRS +Defines the preference-ordered set of base directories to +search for data files in addition to the $XDG_DATA_HOME base +directory. Default is +/usr/local/share/:/usr/share/ + +&tde; adds locations from $TDEDIRS and profiles +as well. Used for .desktop and +.directory menu files. .desktop files under $XDG_DATA_DIRS/applications. +.directory files under +$XDG_DATA_DIRS/desktop-directories + + + + +$XDG_CONFIG_HOME +(&tde; 3.2) - Defines the base directory relative to which user +specific configuration files should be stored. Default is +$HOME/.config. + + + +$XDG_CONFIG_DIRS +(&tde; 3.2) - Defines the preference-ordered set of base directories +to search for configuration files in addition to the $XDG_CONFIG_HOME +base directory. The default is /etc/xdg &tde; adds locations from +$TDEDIRS and profiles as well. Used by .menu descriptions in +$XDG_CONFIG_DIRS/menus. + + + + + + + + +The tdeinit Mystery + + + +tdeinit is used to start all other &tde; +programs. tdeinit can start normal binary program f iles +as well as tdeinit loadable modules +(KLMs). KLMs work just like binary +program files but can be started more efficiently. KLMs +live in $TDEDIR/lib/trinity + +The drawback is that programs started this way appear as +tdeinit in the +output of top and ps. Use +top or ps + to see the actual program name: + + +% ps aux | grep bastian + +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 + + +As you might have noticed, this has another side effect, making it +difficult to kill a process that is causing trouble: + +% killall kdesktop +kdesktop: no process killed + +You might be tempted to try killall +tdeinit, but killing all tdeinit processes will have +the effect of shutting down all of &tde;. In effect, total +destruction! + +There are two simple solutions to this: + +% tdekillall kdesktop +or good old +% kill 26195 +tdekillall is part of the &tde; SDK +package. + + + + + + +Customizing &tde; + + + +Desktop Icons + +&tde; uses several types of icons: + +Documents + +Links to Websites (using .desktop file) + +Links to Applications (using .desktop file) + +Devices - Disks, Partitions & Peripherals: + +Explicit using .desktop file + +Automatic via devices:// io-slave + + + + +Vendor-specific (⪚ &SuSE;'s My Computer) + + + + +Websites + +Links to Websites using .desktop +file: Create +NewFileLink to +Location (URL). Change Icon using +Properties dialogs. The resulting .desktop file: + +[Desktop Entry] +Encoding=UTF-8 +Icon=/opt/trinity/share/apps/kdesktop/pics/ksslogo.png +Type=Link +URL=http://www.kde.org/ + + + + + +Applications + +Links to Applications using .desktop file: Create +NewFileLink to +Application. You must provide details +yourself. Drag from &tde; Menu: Either copy or link (creates symlink), +much easier + + + + + + +[Desktop Entry] +Encoding=UTF-8 +GenericName=IRC Client +GenericName[af]=Irc Kliët +GenericName[de]=IRC Programm +... +GenericName[zu]=Umthengi we IRC +SwallowExec= +Name=KSirc +Name[af]=Ksirc +Name[de]=KSirc +... + + + +Boiler plate + +Translated generic description, not used on desktop + +Legacy, can be removed + +Translated name as it appears on desktop + + + +Desktop Icons + +... +Name[zu]=Ksirc +MimeType= +Exec=ksirc %i %m +Icon=ksirc +TerminalOptions= +Path= +Type=Application +Terminal=0 +X-TDE-StartupNotify=true +X-DCOP-ServiceType=Multi +Categories=Qt;TDE;Network + + + +Supported &MIME; types, not used on +desktop + +The command line to execute + +The icon, from icon theme or full path + +Only used if terminal is +needed + +Working directory for command + +More boiler plate + +Use true if terminal is needed, +text application + +Show bouncy cursor, +disable if it doesn't work. + +Has app started ok? +Remove if it doesn't work + +Categories for &tde; Menu, not +used on desktop + + + + + + + + +The <varname>Exec</varname> option in <literal +role="extension">.desktop</literal> files + +Following the command, you can have several place holders which will +be replaced with the actual values when the actual program is run: + + +%f A single file name; used when dropping +file on icon, or with file associations. + + + + +%F +A list of files; use for applications that can +open several local files at once. + + + + +%u +A single &URL;: if the app can +handle ⪚ &FTP; or &HTTP; &URL;s itself, otherwise &tde;. + + + + +%U +A list of +&URL;s; will download the file first and pass a local file to the app +(!!) + + + + +%d +The folder of the file to open; useful if app needs to +have file in current working directory. + + + + +%D +A list of folders, not very practical. + + + + +%i +The icon; option; &tde; app +will use icon from Icon= line in taskbar. + + + + +%m +The mini-icon; legacy. + + + + +%c +The caption; option; &tde; +app will use name from Name= line in +taskbar. + + + + + + + +Examples: + +Exec line +Command executed +ksirc %iksirc --icon ksirc + +cd %d; kedit $(basename %f)cd /tmp; kedit file.txt + + + + + + + + + + + +Devices + +Links to Devices using .desktop file: +o Create New -> Device + + + + + +Where to Define + +Many places to define Desktop Icons: + + +~/Desktop: +copied from /etc/skel/Desktop + +$TDEDIR/apps/kdesktop/Desktop +(merged) + +$TDEDIR/apps/kdesktop/DesktopLinks +(copied) + +Device Icons (dynamically +merged) + +Distribution Specific SUSE Linux copies certain icons +in starttde.theme from /opt/trinity/share/config/SuSE/default/ + + + + + + + +&tde; Menu + + +How it Works + +In &tde; 3.2 a common menu format is introduced at +http://freedesktop.org/Standards/menu-spec/ +Before &tde; 3.2: + + +Directory structure under share/applnk + +Directory structure represents menu +structure + +Each .desktop file +represents a single application + + + + +It was difficult to rearrange the structure in &tde; 3.2 so the +new menu format: + +Defines structure in a single .menu file +Is based on categories +is shared between GNOME and &tde; +Supports applnk style menus as well + + + + +Example from kde-applications.menu: + + + <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> + + + +Menu entry with 3 applications: + + +/usr/share/applications/Acrobat +Reader.desktop + +/opt/trinity/share/applications/tde/kpresenter.desktop + +/opt/trinity/share/applications/tde/kword.desktop + + + + + + + +Stored Where? + +.menu files describing the +menu structure. The files are stored in $TDEDIR/etc/xdg/menus and +/etc/xdg/menus. These store the +system-wide menu structure and are controlled by +$XDG_CONFIG_DIRS. $HOME/.config/menus stores +user-specific changes to the menu structure and is controlled by +$XDG_CONFIG_HOME. For more information, see http://www.freedesktop.org/Standards/basedir-spec. + +.desktop files describe the +applications and are stored in: $TDEDIR/share/applications, +/usr/share/applications, +/usr/local/share/applications. These are +the system-wide application .desktop files which are controlled by +$XDG_DATA_DIRS. + +$HOME/.local/applications +contains user-specific .desktop +files and user-specific changes. It is controlled by +$XDG_DATA_HOME. For more information, see http://www.freedesktop.org/Standards/basedir-spec + + +.directory files describing +the sub-menus are stored in: $TDEDIR/share/desktop-directories, +/usr/share/desktop-directories, /usr/local/share/desktop-directories. +These are the system-wide menu .directory files, controlled by +$XDG_DATA_DIRS. The user-specific changes are stored in $HOME/.local/desktop-directories. +These are controlled by $XDG_DATA_HOME. For more +information, see http://www.freedesktop.org/Standards/basedir-spec + + +Example from kde-applications.menu: + + + <Menu> + <Name>Art</Name> + <Directory>suse-edutainment-art.directory</Directory> + <Include> + <Category>X-SuSE-Art</Category> + </Include> + </Menu> + + + + +Art is the internal name for this +menu. suse-edutainment-art.directory defines the +name and icon for this menu, and the menu includes all applications +that have X-SuSE-Art listed as a category, ⪚: + +Categories=Qt;TDE;Education;X-SuSE-Art + + +suse-edutainment-art.directory defines the +name and icon for this menu: + +[Desktop Entry] +Name=Art and Culture +Icon=kcmsystem + + + + + + +Common Pitfalls + +Applications not in the menu do +not 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. + +When applications are unwanted in the menu, either place them in +.hidden menu or a dedicated menu with + +NoDisplay=true + in the .directory file + + + +Essential Menus + +$TDEDIR/etc/xdg/menus/applications-merged/ +contains kde-essential.menu which includes some +essential menus that are normally not shown in the &tde; menu itself: + +Control Center has a hidden Settings menu whose +contents are defined by kde-settings.menu and +whose icon and name are defined by kde-settings.directory + +Info Center has a hidden Information menu whose +contents are defined by kde-information.menu and +whose icon and name are defined by kde-information.directory. + + +Screensavers contains a hidden System/Screensavers menu, +whose contents are defined by +kde-screensavers.menu and whose icon and name +are defined by +kde-system-screensavers.directory. +$TDEDIR/share/desktop-directories/kde-system-screensavers.directory +contains: + +NoDisplay=true + + + + + + + +Old-Style Menus + +&tde; continues to support old-style menus that are defined by +the directory structures in $TDEDIR/share/applnk +(system wide) and $HOME/.trinity/share/applnk +(user specific). This is observed unless the .desktop file has a Categories= line. In that case the categories determine the location in the menu. + + + +<application>KSycoca</application> +KSycoca caches menu structure and +information about all available applications. You can rebuild the +database with +tdebuildsycoca. The database +which is built lives in /var/tmp/tdecache-${USER}/tdesycoca. +It is automatically updated by KDED, +checked during &tde; login, and KDED +watches for changes while logged in. + +To disable watching for changes (since it may hurt over NFS) add +the following to kdedrc: + +[General] +CheckSycoca=false + + + +To force regeneration, run touch $TDEDIR/share/services/update_tdesycoca. + + + + +&kmenuedit; + +&kmenuedit; is aimed at a single user setup. Changes to menu +structure are saved to +~/.config/menus/applications-tdemenuedit.menu, +changes to applications are saved in ~/.local/share/applications/ and changes +to sub-menus (icon, name) are saved in ~/.local/share/desktop-directories/. The +KIOSK Admin Tool uses &kmenuedit; and copies the above changes to +profile- or system-wide locations. + + + + + + + + +&tde; Panel + +The &tde; panel is also known as &kicker;. It is modular and +consists of the following components: + +Applets +Application buttons +Special Buttons + + + +By default, the panel contains the following applets: + +Pager - shows the virtual desktops +Taskbar +System Tray +Clock + +and the following special buttons: + +&tde; menu +Desktop Button + + + +Various application buttons are also added, space permitting: + +Home Button +Browser Button +KMail Button + + + + + +File Associations + +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 $TDEDIR/share/mimelnk and +each application's .desktop file +contains a list of &MIME; types supported by that application. + + +kview.desktop: + +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 + + + +kuickshow.desktop: + +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 + + + +Both can open image/gif Which one is used to open a .gif file? + +The application with highest +preference!. kview.desktop contains + +InitialPreference=3 + +whereas kuickshow.desktop contains + +InitialPreference=6 + +Therefore, &kuickshow; will be used to open .gif files. + + +How can we make &kview; default? + +A user can change file association in the +&kcontrolcenter;. These changes are stored in +$HOME/.trinity/share/config/profilerc. +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. + + + + + + + + +Locking Down &tde; + + +How It Works - The Basics + +&tde;'s lock down features are centered around the following +options: + + +Make +configuration options immutable +Restriction of specific +actions +Restrict access to certain +&URL;s +Restrict access to +certain configuration modules + + + + + +Immutable Configuration Options +Locking Down &tde; + +Immutable options allow system administrator to provide default +settings that can not be changed by the user. + +Pre-existing configuration options of the user will be ignored once a +configuration option is made immutable. + +Options can be controlled either on a per entry basis, per group of +entries or on a file by file basis. + +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. + +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. + + + + +Action Restrictions + +&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. Save Document 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 Save +Document action is . 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 restriction which disables all +functionality that would offer the user access to a &UNIX; shell. + + +Restrict User Access to Shells + +In order to prevent the user access to a command shell we can restrict +the action by adding the following to +kdeglobals: + + +[TDE Action Restrictions] +shell_access=false + +Since this affects the &tde; menu and the available applications, we +must force an update of the sycoca database: + +touch $TDEDIR/share/services/update_tdesycoca + +Now re-login to &tde; and check the following points: + + +The &kmenu; +In &konqueror;, +ToolsOpen +Terminal +The &Alt;F2 run +command + + +Full documentation about available actions can be found on http://www.kde.org/areas/sysadmin/. + +A few of the more interesting actions are listed below: + + + + +The Configure option form the +Settings menu + + + +The Report Bug/Request Enhancement... option from the +Help menu. + + + +&RMB; mouse button menu on the desktop. + + + +&RMB; mouse button menu on the panel. + + + +Hide all actions or applications that require root access. + + + +Hides all actions or applications that provide shell +access. + + + +Disables the option to select the printing system +(backend). + + + +Whether the user will be able to lock the +screen + + + +Whether the user may start a second X session (see also +&tdm;) + + + +Whether OpenGL screensavers are allowed to be +used. + + + +Permit screensavers that do not hide the entire +screen + + + + + + +&URL; Restrictions + +There are three types of restrictions that can be applied to +&URL;s: + + + +list +To control whether a directory listing is +allowed. + + +open +To control whether certain &URL;s can be +opened + + +Redirect +To control whether one &URL; can open another &URL;, either +automatically or via a hyperlink. + + + +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. + +The following rules disable opening http and https &URL;s outside +.ourcompany.com: + + + + + + +[TDE URL Restrictions] +rule_count=2 +rule_1=open,,,,http,,,false +rule_2=open,,,,http,*.ourcompany.com,,true + + + +The first four commas skip over the selection criteria with respect to +the originating &URL;. This part is only needed with redirect type +rules. + + forbids the +opening of any http or https &URL; + allows the +opening of any http and https &URL; in the .ourcompany.com domain. Note the wildcard +* is only allowed at the start of a domain. + + +The following rules makes that the user can no longer browse +directories on the local file system that are outside his +$HOME directory: + + + + + +[TDE URL Restrictions] +rule_count=2 +rule_1=list,,,,file,,,false +rule_2=list,,,,file,,$HOME,true + + + forbids the +listing of any local directory + allows listing +directories under the users own $HOME +directory. + + +$HOME and $TMP are special values to +indicate the users home directory and the &tde; temporary directory of the +user, ⪚ /tmp/kde-bastian + +The following rules makes that the user can no longer open local files +that are outside his $HOME directory: + + + + + + +[TDE URL Restrictions] +rule_count=3 +rule_1=open,,,,file,,,false +rule_2=open,,,,file,,$HOME,true +rule_3=open,,,,file,,$TMP,true + + + forbids the +opening of any local file + allows opening +files under the users own $HOME directory. + 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. + + + +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. + +For example, if we want to give the intranet-server www.mycompany.com the possibility to refer +to local files we could add the following rule: + +[TDE URL Restrictions] +rule_count=1 +rule_1=redirect,http,www.mycompany.com,,file,,,true + +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: + + + +:local +Protocols that access locally stored information, examples +are file:/, man:/, fonts:/, floppy:/ + + +:internet +Common internet protocols such as http and +ftp + + + +Information about protocols is stored in *.protocol files stored in +$TDEDIR/share/services. + +The = entry defines the group a protocol is part +of: +grep +$TDEDIR/share/services/*.protocol + +General rules: + + +The :local protocols may refer to any other +protocol +It's always allowed to refer to an :internet +protocol +Not all protocols are part of a group, fish:/ for +example. + + + + + +Configuration Modules + +&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. + + +The proxy configuration module appears in the Control Center but also +as part of the Configure Konqueror dialog in +&konqueror; + +Individual configuration modules can be started with +tdecmshell module + +To start the Proxy module use: + +tdecmshell +tde-proxy.desktop +tdecmshell proxy + + +Not all applications use configuration modules, often the +configuration dialog is an integral part of the application +itself. + + +All configuration modules are strictly speaking part of the &tde; +menu. + + + +The modules that are visible in the Control Center normally +have a .desktop file in $TDEDIR/share/applications/tde +and are sorted under the hidden Settings-Modules menu by +the kde-settings.menu, included from +kde-essential.menu +tdebuildsycoca 2> /dev/null | grep Settings-Modules + + +Application specific modules normally have a .desktop file under +$TDEDIR/share/applnk/.hidden which +corresponds to the hidden .hidden menu, included as a result of +<KDELegacyDirs/> +tdebuildsycoca 2> /dev/null | grep .hidden + +In &tde; 3.3 it is possible to edit the Control Center with +kcontroledit. +kcontroledit works just like +kmenuedit, changes for current user only. Use +kiosktool to make changes for +everyone. + + +Individual configuration modules can be disables by adding the +following to kdeglobals: + +[TDE Control Module Restrictions] +module-id=false +For example, to disable the proxy module use +[TDE Control Module Restrictions] +tde-proxy.desktop=false +Check the Control Center and the Configure +Konqueror dialog if the proxy configuration is still +there. + + + + + + +The Lazy Admin + + + + + + + +Remote Desktop Sharing + +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. + +Remote desktop sharing involves two applications: &krfb; (&tde; remote +frame buffer, a VNC server) and &krdc; (&tde; remote desktop connection; a +VNC client.) + +&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. + +Incoming connections are handled by the kinetd kded module. You can +use the command dcop kded kinetd +services 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. + + + + + + +&tde; DIY - Building Your Own Tools + + +DCOP + + +Desktop COmmunication Protocol, DCOP, is a lightweight mechanism for inter-process communication. +DCOP allows the user to interact with programs that are currently running. +&tde; supplies two programs to utilitize DCOP: +dcop, a command-line program, and +kdcop, a GUI program. + + +A few notes about using dcop: + + + + + + +dcop [options] [application [object [function [arg1] [arg2] ... ] ] ] + + + + +Applications that can open more than one window at a time will be listed as +<application>-PID + + + + +All the arguments are case-sensitve. setFullScreen and setfullscreen are two different functions. + + + + +The regular expression token * can be used in the application and object arguments. +% dcop +konqueror-16006 +konsole-8954 + + + + + + + + +Some example commands and their output are below: + + + +% dcop +konsole-8954 + +One &konsole; is running with a PID of 8954. + +% dcop +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 + +Here you see that there are four sessions running. + +% dcop +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() + +Here are the options for the main &konsole; program. + + +% dcop +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) + +Here are the options for the first session, session-1. + +% dcop true + +This sets &konsole; to full screen. + + + + +When there is more than one application/object, which one should you use? + Got a reference? + +% echo +DCOPRef(konsole-7547,konsole) + +% dcop +session-6 + +% dcopstart +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' + + + + + + +KDialog +&tde; DIY - Building Your Own Tools + +You can use &tde; dialogs from your own scripts, to combine the power +of &UNIX; shell scripting with the ease of use of &tde;. + +kdialog + +kdialog + +The KDialog part can be replaced via + option + +kdialog + +Saves whether to show again in +$TDEHOME/share/config/myfile (by writing +into this file the following lines: + +[Notification Messages] +mykey=false + +Instead of you can also use + and , as appropriate. For +instance, you might use kdialog or kdialog +. + +It is also possible to create message boxes that accept a yes or no +answer. + +kdialog echo $? + + + + + +Return Value +Meaning + + + +0Yes, OK, Continue +1No +2Cancel + + + + +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 + here as well, it will remember the users choice +and returns it the next times without showing the dialog any more. + +Further variations are: + + + + + +like but with a different +icon + + + + +With Continue and +Cancel buttons. + + + + +With Yes, No +and Cancel button. For example: +kdialog + + + + +kdialog + +The result is printed to stdout, to put it in a variable you can use +name=$(kdialog --inputbox "Enter your name:" +"YourName"). The last argument is optional, it is used to +pre-fill the dialog. + +password=$(kdialog ) + +The option does not work with + or + +There are two dialogs that let the user make a choice from a +list: + + + + + +Lets the user select a single item from a list. + + + + + +Lets the user select one or more items from a list. + + + + +city=$(kdialog ) + +$city will a, b, c or d. + +city=$(kdialog ) + +Madrid and Paris will be pre-selected. The result with Madrid and +Paris selected will be "b" +"c". + +If you add the option, it will put +b and c each on a line +of its own, making the result easier to process. + +file=$(kdialog --getopenfilename $HOME) +file=$(kdialog --getopenfilename $HOME "*.png *.jpg|Image Files") +file=$(kdialog --getsavefilename $HOME/SaveMe.png) +file=$(kdialog --getexistingdirectory $HOME) + + + + + + + +&groupware-with-kontact; + + -- cgit v1.2.3