K Module -> KDE Autostart Guide
Ready, Set, Go!
The Ultimate Guide to KDE Session Management and Autostarting
Version 1.0 - 20080422
- Getting Started
- KDE Session Management [Basic]
- Details, Details [Advanced, Optional]
- And Away We Go!
- Endnotes
- References
I. Getting Started
One of the most frequently asked questions (FAQ) about KDE is how to start applications when the user logs into a KDE session. The answer is not always as straightforward as one would hope, and sometimes quite scattered across several sources. This guide attempts to complete guide to how to manage sessions and autostart applications in KDE, as well as to provide a central reference for links related to the topic.
The first part of this guide gives easy instructions on how to use KDE's powerful session management and on how to start apps after logging into KDE. The third part gives a bit more technical (but not so heavy) details on the startup process and tips on how to take advantage of that.
This guide only applies to KDE 3.5.9. I'll be updating with KDE 4 information it once I've played enough with the new tools.
II. KDE Session Management
KDE has a very powerful session management system, handled by ksmserver. Not only is it able to save and restore applications from previous sessions, it can also save the *state* of KDE applications. This means that ksmserver remembers what applications are open, where the windows are located, as well as what those applications were doing. For example, if you left KWrite open with some text file, KDE will remember that and will restore KWrite with the same text file the next time you log in. If you have unsaved work, you will be prompted whether you want to save it.
Unfortunately, the state of non-KDE apps are not saved in a session and only their window locations are included. The user has to make sure that he or she saves whatever is opened in those apps. KDE will not warn them before logging out if an opened file needs to be saved first. Also, KDE will not be able to restore whatever files those apps have opened when you logged out. [1]
You can control KDE's Session Management options in KControl -> KDE Components -> Session Manager. (Kubuntu users will see it in System Settings -> Advanced tab -> Session Manager). For the purpose of running apps on startup, we just need to focus on the On Login and Advanced options, indicated by the highlighted areas in the images below.
A. Login options
There are three ways ksmserver handles sessions when logging in:
1. Restore previous session
This is the default behavior. KDE will automatically save the session when you logout and will restore it the next time you log back in. KDE will save remember the applications and windows that were left open, their locations, as well as their state (for KDE-aware apps). This is also the easiest way to start apps when you login. Just leave those apps running before you logout. However, this works best with KDE applications only. Remember that non-KDE apps only get started when logging in, but their states are not saved nor restored. Non-GUI programs such as scripts or processes also do not get saved. It can also be a bit cumbersome at times, when you fail to close some apps before logging out.
2. Restore manually saved session
Midway between automatically saving sessions at logout and not saving sessions at all is the option to control when a session is saved and what will be saved in the session. Once this option is chosen (and the Apply button is clicked), a new entry in the K Menu appears: Save Session. Selecting this menu entry will let you save a "snapshot" of the session which will be restored the next time you log in. You can save the session at any point in time and as many times as you want, but only the most recent snapshot is remembered. When this option is used, the session is no longer automatically saved when logging out.
3. Start with an empty session
At the other extreme of the pendulum, this option disables KDE from restoring any saved session. This will start KDE with a blank slate everytime, with only system-define apps autostarted on logging in. This is usually used in tandem with manually defining autostarted apps, which will be discussed in a while. When using this option for the first time after a fresh install of a KDE Linux or BSD distribution, keep in mind that some distributions might be using saved sessions to restore some applications that you would normally see when you login, such as KMix or Katapult in Kubuntu. Take note of what apps are restored on your distribution and which ones you'd like to keep autostarting.
4. Excluding applications
Before we jump to the next method, let's consider one more scenario. Let's say you've chosen to restore automatically or manually saved session and there are some apps that you always forget to close before you logout or save the session. What if you didn't want them to be saved and restored? KDE allows you to list programs that you want to be excluded from sessions. At the bottom part of the Session Manager dialog, you can enter a list of programs (using their executable filenames) that you don't want to be saved and restored in sessions, separated by commas with no spaces in between.
The Session Manager control module has some other features that you can read about by clicking on the "What's This" button (the one with the question mark at the upper right corner of the window) and clicking on an area of interest. You can also read the documentation by clicking on the Help button or reading it online. [2]
B. Manual Autostart
You can also specify one by one what apps you want to get autostarted when you login. While this might be a bit troublesome to setup at first, specially if you want to autostart many items, it gives you more control over those items and usually need to be done only once. This way of autostarting apps is commonly used when the Session Manager is set to start with an empty session, but it can also be used together with the other two options.
Manually autostarting applications simply involves putting items into the $KDEHOME/Autostart folder. $KDEHOME stands for the current user's place for storing KDE settings and data, usually ~/.kde (/home/username/.kde) in KDE 3.5 systems. You can easily go to this location by typing ~/.kde/Autostart in Konqueror's location bar, or by clicking Go -> Autostart from Konqueror's menu bar (Kubuntu users will have to type the location themselves).
1. Drag and Drop
There are two ways to put items into the Autostart folder. The simplest method is by drag and drop. You can either open two Konqueror windows or one window split into two views using the Window menu options (Kubuntu users, right-click on the Konqueror status bar). Point one window/view to the Autostart folder and the other window/view to the location of the program, for example, /usr/bin/ or /opt/bin/. Select the program you want to autostart, drag and drop it to the Autostart folder. A menu will pop up asking what action you want to take. Choose either Copy Here or Link Here (recommended action), never Move Here unless you know exactly what you are doing. You can also drag entries from the K Menu and drag them into the Autostart folder. This will create either a copy or link to that menu entry's .desktop file (which will be tackled later).
And that's it. The next time you login, whether or not Session Manager restores a previous session, those items in will get started.
2. .desktop Files
While the method above is simple and easy, you can have greater control over the behavior of those applications by creating .desktop files that describe and point to those apps. Don't worry, you don't have to type in the contents of these files since there is a full graphical system for creating them. .desktop files, or more properly Desktop entry files, are a Freedesktop.org standard for describing how an application is launched or appears in menus and is used for main menu items and desktop icons. [3] So some of the steps and information you will see here can also be used in other places, such as K Menu entries and Desktop icons.
Right click on an empty space in the Autostart folder and select Create New -> Link to Application from the context menu that appears. A dialog box will pop up where you can enter the details for the application that you want to autostart. We don't need to fill in all the details and we'll just focus on the relevant ones. In the General tab, you can set the details of the Desktop file that will be created such as its name and appearance. You can give it an icon by clicking on the icon box at the left.
In the Application tab, you can fill in the details for the application that will be run. The most important part of this tab is the Command field, where you enter the command that will run the program you want to autostart. The Name and Description fields are important if the .desktop file is going to be used in menus. Clicking on the Advanced Options button will give you fine-grained control over how the program is started. The Run in terminal option is very useful for running text-based programs inside a Konsole window, and setting it to Do not close when command exits makes sure that the Konsole windows doesn't disappear once the program finishes running so that you can read any needed output. You can also uncheck Enable launch feedback so that you will not get any bouncing cursor or flashing taskbar when the program starts, making it start quietly in the background.
You can get more information on the various options in the Link to Application dialog box by clicking on a field or option and pressing Shift+F1 (or doing it in reverse... the dialog box can be weird that way).
Once you are done filling in the details that you want, click OK so that the .desktop file will be created in the Autostart folder. When you login the next time, programs linked to in the .desktop files will be started. The great thing about the Autostart folder is that anything you put in there will get run or opened after logging in. This means anything from symlinked programs, .desktop files, scripts, documents, images, or any other kind of file. Remember to make the scripts that you put into this folder executable by the user.
Armed with this knowledge, you can now go crazy with autostarting your favorite apps and files. Just don't over do it. :D
III. Details, Details
The instructions above is basically all you need for managing your KDE sessions and autostarting apps at login. But of course, KDE is not content with just providing the basics. With a little bit of knowledge into the KDE startup process, you can fine tune your sessions even more. Power users and tweakers rejoice! This part is for you.
A. Sneak peek into starting KDE
It's not actually necessary to understand all the details of KDE's startup process to be able to autostart apps. But it does pay to know some of the basics, like important locations and the order of autostarting apps. Two such important locations are $KDEHOME and $KDEDIR or $KDEDIRS. $KDEHOME is the location in the user's home directory where KDE settings and application data for that user are stored. This usually defaults to ~/.kde/ for KDE 3. $KDEDIR is the location where KDE is installed, which therefore contains global (for all users) settings and data. This location varies from distribution to distribution. $KDEDIR, however is quite old (used by KDE 2), and KDE 3 now uses $KDEDIRS, which can contain multiple locations, each of which has KDE applications installed, one of which is $KDEDIR. [4] Some distributions do not explicitly set these environment variables, in which case you can use the kde-config command to find them.
kde-config --prefix will give you where KDE is installed, the value of $KDEDIR
kde-config --localprefix will tell you the user's $KDEHOME
If $KDEDIRS is not set, it defaults to $KDEDIR. [5] Keep these locations in mind as we go through the startup process.
The startup process is initiated by the startkde script when the users logs into a KDE session from KDM or by running the script explicitly. The startkde script is responsible for launching kdeinit, the master process that starts all other processes, as well as passing control over to ksmserver, the KDE session manager. One fact about this script is that some time before it passes control to ksmserver, it goes through some directories and checks if there are scripts that it can run. startkde first goes over the $KDEHOME/env/ directory (for example, ~/.kde/env/) and checks if there are shell scripts there that end in .sh. If there are, it tests each script if they are readable by the user and runs them if they are. Next, it goes over the $KDEDIR/env/ directory (for example /usr/env/) and does the same. So user-specific ($KDEHOME) scripts are first run before system-wide ones ($KDEDIR).
The startup flow soon passes to the session manager, ksmserver. ksmserver is not only responsible for restoring sessions, but as well as starting other processes. The first thing that it does is to bring up the window manager defined by the $KDEWM variable (which is KWin by default if not set). After this, it goes through the Desktop entry (.desktop) files in $KDEHOME/share/autostart/ and runs them as indicated by those files. ksmserver manages the startup of other processes, and somewhere in between, it restores the previous session, depending on the option chosen by the user. And finally, ksmserver goes through $KDEHOME/Autostart and opens any file located in that directory. Now the desktop is ready for use. You can read the nitty gritty details of what ksmserver does in the README file that comes with its source code. [6]
Once a session is ended (when the user logs out), control is passed back to the startkde script, which then performs some cleanup routines. One significant thing it does is that it goes over directories to check for scripts to be run before "shutting down". First, startkde goes over the $KDEHOME/shutdown/ directory and checks for any file that does not end in ~ or .bak, tests whether they are executable by the user and runs them if they are. It then goes to the $KDEDIR/shutdown/ directory and does the same. And thus ends a normal KDE session. You can check what startkde actually does by opening the file in a text editor (it's just a script) or reading it online. [7]
B. Putting it all together
So what does all that mean? It tells us what directories are scanned for items, what kind of times are accepted, and when they are run.
1. $KDEHOME/env and $KDEDIR/env
These are the first locations scanned during startup. Scripts here should end in .sh. They must be readable by the user if they are to be executed. They don't need to be executable, but it's a good idea to still make them so. User-specific scripts are run first before system-wide ones, so scripts that you want to run for any user should be put in $KDEDIR/env/. Since these locations are scanned before any window manager is started, this is a good place to put scripts that set environment variables like $KDEWM or $PATH (as we'll see later), or scripts that don't need a GUI. For anything else, the autostart directories should be used.
2. $KDEDIR/share/autostart
This is the system-wide autostart directory, scanned for every user that logs in. It is sourced only after the window manager is set up by the Session Manager. Unlike the other locations, only Desktop entry (.desktop) files are run here.
3. Restore Session
Depending on the session management option set in KControl, ksmserver restores a previous session.
4. $KDEHOME/Autostart
This is the user's autostart directory, only sourced for the specific user. As mentioned already, any file in this directory gets opened at this point. If the file is an executable program, it is run. Otherwise, it is opened using the default application for that file type. [8]
5. $KDEHOME/shutdown/ and $KDEDIR/shutdown/
This locations are sourced when the user logs out, just before startkde terminates. This is a good place for cleanup scripts or commands that stop processes started in env/. Like the env/ directories, $KDEHOME/shutdown/ is searched first before $KDEDIR/shutdown/. However, scripts in the shutdown/ directories do need to end in .sh. They must be executable and should not end in either ~ or .bak.
So in summary:
* If you need to set some environment variables that you want KDE to be able to see, or run a command *before* KDE starts, put a script in $KDEHOME/env/. If you want the scripts to be run by any user that logs in, put them in $KDEDIR/env/
* If you need to start something *after* KDE has started and want to make it available for all users, create a .desktop file in $KDEDIR/share/autostart/
* If you want programs or files to be opened for a particular user after KDE has started, put them in that user's $KDEHOME/Autostart/
* Scripts that need to be run when logging out need to go in $KDEHOME/shutdown/ or $KDEDIR/shutdown/. Make sure the scripts are executable.
C. Tips
Here are some practical tips
1. KDE and .bash_profile
Login managers, such as kdm, don't source ~/.bash_profile, so items that you put in there are not available to KDE, unless you use them in Konsole. So if you have a new directory in your $PATH and set that up in ~/.bash_profile, then KDE will not be able to see that, for example, when you try to start a program in the Run Command dialog box (Alt+F2). The best way to get around this is to make a script that will source ~/.bash_profile and put that in $KDEHOME/env/ or $KDEDIR/env/, if you want each user's ~/.bash_profile sourced when he or she logs in.
(However, if you want ~/.bash_profile to be sourced even in non-KDE sessions, you'll have to put the script or command in a more "low-level" location, such as Xsession or .xsession files [9]).
An example script would be:
| source_bash.sh |
#!/bin/sh</p> if [ -f ~/.bash_profile ]; then source ~/.bash_profile fi |
2. Using a different WM
Since KDE 3.2, it has been possible to use a different window manager in a KDE session. (You could just choose a different window manager session from kdm, but that wouldn't be the same thing). KDE uses the $KDEWM environment variable to check what window manager will be started by the Session Manager. If unset, ksmserver will fall back to KWin. [10] If you want to use a different window manager, set $KDEWM to the window manager's executable file, and since you're going to set an environment variable, specially one that needs to be set *before* any GUI is started, you must put a script setting $KDEWM in $KDEHOME/env/.
| wm.sh |
#!/bin/sh export KDEWM=/usr/bin/icewm |
Just take note that Kicker, the KDE Panel, will still be started, since it is started when $KDEDIR/share/autostart/ is sourced, after the window manager is started. So in case you prefer to use the panel that the window manager provides, you will have to disable Kicker. [11]
3. "Cheat sheet"
Just remember (in order):
| Location | Which user? | File requirements |
| Before KDE starts: | ||
| $KDEHOME/env/ | Current user | Must end in .sh |
| $KDEDIR/env/ | All users | Must end in .sh |
| After KDE starts: | ||
| $KDEDIR/share/autostart/ | All users | Must be .desktop files |
| Restore Session | ||
| $KDEHOME/Autostart/ | Current user | any kind of file or program |
| After KDE session: | ||
| $KDEHOME/shutdown/ | Current user | Must be executable |
| $KDEDIR/shutdown/ | All users | Must be executable |
IV. And away we go!
So as you can see, KDE has a very elaborate and flexible system in place for automatically running programs or opening files for almost any given situation. You don't really need to know all the advanced details. And for most people, they won't even need to go beyond the basic instructions given at the beginning of this guide. Of course, it's not entirely easy doing all these by hand, or keeping track of 3 or more directories. There are some GUI tools that help make it easier, such as the Autostart Manager [12] and KDE 4 even comes with one built-in. Whatever the case may be, KDE gives you, the user, the ability to customize your sessions to fit your needs or whims, giving you the power to conquer your desktop. With KDE, you can truly Be Free.
Endnotes:
- Quickstart Guide, Logging out [Note: That document seems to be outdated. KDE 3.5.9 does not behave as described]
- Session Manager KCM
- freedesktop.org Desktop Entry Specification
- About your KDE Account
- Specifying KDE Directories
- kdebase/ksmserver/README
- kdebase/startkde [Note: OK, startkde doesn't really use $KDEHOME and $KDEDIR, but for the sake of simplifying the discussion, only these two locations are used]
- Techbase: Session Management and Autostart
- FAQ: KDE (kdm) does not read my .bash_profile!
- KDE 3.2 and other window managers
- KDE Hidden Configuration: Disable kicker
- Autostart Manager [Note: This is a bit outdated and seems to have problems with the env/ and shutdown/ requirements]