# The &kdm; Handbook

## Introduction

&kdm; provides a graphical interface that allows you to log in to a system. It prompts for login (username) and password, authenticates the user and starts to run a "session". &kdm; is a "drop-in" replacement for xdm, the X Display Manager, and is superior to it in a number of ways.

The user-interface to &kdm; is through two dialogue boxes. The main dialogue box has these features:

- A "Login" field for you to enter your username.

- A "Pass" field for you to enter your password.

- A region to the left of the "Login" and "Pass" fields which can be used to display either a static image or an analogue clock.

- (Optionally) a graphical image of each user (for example, a digitised photograph). Clicking on an image is equivalent to typing the associated username into the "Login" field. (This feature is an imitatation of the login box on IRIX).

- A "session type" drop-down box that allows &kdm; to be used to start sessions with various different window managers or desktop environments installed on the system, including KDE, KDE2 and GNOME.

- A "Go!" button that validates the username/password combination and attempts to start a session of the selected type.

- A "Cancel" button that clears the text from the "Login" and "Pass" fields.

- (Optionally) a "Shutdown" button that displays the "Shutdown" dialogue box.

The "Shutdown" dialogue box presents a set of radio buttons that allow one of these options to be selected:

Shutdown

- Shut the system down in a controlled manner, ready for power-down.

Restart

- Shut the system down and reboot. For systems that use Lilo, an optional drop-down box allows you to select a particular operating-system kernel to be used for the reboot.

Restart X Server

- Stop and then restart the X-server. Typically, you might need to use this option if you have changed your X11 configuration in some way.

Console Mode

- Stop the X-server and return the system to console mode. This is achieved by bringing the system down to run-level 3. Typically, the system manager might need to use this option before upgrading or re-configuring X11 software.

Pressing the "OK" button initiates the selected action; pressing the "Cancel" button returns to the main &kdm; dialogue box.

The next chapter explains how to configure &kdm;. Subsequent chapters describe how to configure your system in order to use &kdm;, how to build and install &kdm; from source, and how to learn more about &kdm; and the KDE project.

## Configuring &kdm;

This chapter assumes that &kdm; is already up and running on your system, and that you simply want to change its behaviour in some way. If your problem is more serious, skip forward to later chapters.

When &kdm; starts up, it reads its configuration from the file `kdmrc`. Since &kdm; must run before any user is logged in, it is not associated with any particular user. Therefore, it is not possible to have a user-specific `$HOME/share/config/kdmrc` file; all users share the common version of `kdmrc`, located in `$KDEDIR/share/config/kdmrc`. It follows from this that the configuration of &kdm; can only be altered by those users that have write-access to `$KDEDIR/share/config/kdmrc` (normally restricted to system administrators logged in as "root").

You can view the `kdmrc` file currently in use on your system (located by default at `$KDEDIR/share/config/kdmrc`), and you can configure &kdm; by editing this file. Alternatively, you can use the graphical configuration tool provided by the KDE Control Centre (under Applications System Login Manager), which is described in the KControl help files.

The remainder of this chapter describes the contents of the `kdmrc` file. If you are happy using the graphical configuration tool, there's no need to read any further.

There are four sections in `kdmrc`:

### KDM

The keys in this section are:

    StdFont
    FailFont
    GreetFont
    GreetString
    SessionTypes
    LogoArea
    LogoPixmap
    ShutdownButton
    Shutdown
    Restart
    ConsoleMode
    UserView
    Users
    NoUsers
    SortUsers
    GUIStyle

A short description of the keys:

`*Font`

- A fontsstring formatted like this: Courier,12,5,iso-8859-1,50,0.

`GreetString`

- The title of the &kdm; login window.

`SessionTypes`

- A comma-separated list of session arguments, usually used to select a particular window manager. Defaults to `SessionTypes=kde,failsafe`.

`LogoArea`

- Controls what appears in the lower left-hand corner of the login window. Can be either `KdmLogo` (in which case the image specified by `LogoPixMap` is displayed) or `KdmClock` (in which case a clock is displayed).

`LogoPixmap`

- Specifies the image to be displayed in the lower left-hand corner of the login window when LogoArea=KdmLogo.

`ShutdownButton`

- ShutdownButton controls when the shutdown button is displayed and can be one of `All`, `None`, `RootOnly` and `ConsoleOnly`. The meaning of `All` and `None` is very clear. If you choose `ConsoleOnly` you can't do a remote shutdown. If you choose `RootOnly` you will be prompted to enter the root password before the shutdown will proceed.

`Shutdown and Restart`

- The commands to run on system shutdown and restart, respectively. (Defaults: `/sbin/halt` and `/sbin/reboot` respectively.

`ConsoleMode`

- The command string used by the Console Mode option of the "Shutdown" button. (Default: `/sbin/init `3``). This option is not available under BSD.

`UserView`

- If this is set to "`1`", a graphical view of users will be displayed in the &kdm; window.

`Users`

- A comma-separated list of usernames that will be displayed in the graphical user view. If `UserView` is set to "`1`" and the `Users` entry is missing, &kdm; will look for users in the password file `/etc/passwd`. The users displayed are those who have a real name beside their login name, a home directory and a default shell - the rest are skipped. &kdm; will look in `$KDEDIR/share/apps/kdm/pics/users/` for an icon for each user. If an icon named `johndoe.png` exists, &kdm; will use that for displaying user johndoe. If not, &kdm; will use `default.png`.

  &kdm; is able to handle icons of different sizes, but the result looks messy. The solution to this is to use an application such as KDE's Pixie, (or the GNU Image Manipulation Program, (gimp) or John Bradley's XV,) to convert all your images to the same size. A size of 64x64 should give enough resolution, and matches the default icons provided. These two programs can also be used to convert images from various formats into png format.

`NoUsers`

- A comma-separated list of usernames that won't be displayed. Use it to filter "pseudo-users" like `sync` and `shutdown` from the user view.

`SortUsers`

- If set to "`0`", the list of users are displayed in the order it was read. The default is to display users in sorted order.

`GUIStyle`

- Can be either `Motif` or `Windows`.

### KDMDESKTOP

This section is obsolete. In previous versions of &kdm; it could be used to control a background screen prior to login. The graphical configurator for &kdm; may still generate this section, but it is ignored by &kdm;.

### Locale

This section is handled by a standard KDE library. The only keys that are likely to have any effect are:

    Country
    Language
    Charset

A short description of the keys:

`Country`

- indicates the country. Look in `$KDEDIR/share/locale/l10n` for the complete list of country codes supported by your system. The country code is used to locate the file `$KDEDIR/share/locale/l10n/country_code/entry.desktop` which is used to provide locale-specific information such as time and date formats and the local currency symbol.

`Language`

- indicates the language to use for &kdm; (default: `C`, representing US English). The value can be over-ridden by the `KDE_LANG` environment variable.

`Charset`

- indicates the character set to use (default: `iso-8859-1`).

If you change the keys but all the dialogue text remains in English, this probably indicates that you do not have the translations installed on your system.

### Lilo

Lilo (Linux Loader) is a boot manager that is often used on GNU/Linux systems. Lilo comes with extensive documentation (see man lilo as a start). This section configures mechanisms for restarting the system using Lilo. The keys are:

    Lilo
    LiloCommand
    LiloMap

A short description of the keys:

`Lilo`

- Controls whether Lilo is used to restart the system (default: `FALSE`). When this key is set to `TRUE`, the "shutdown" dialogue box contains an extra drop-down configuration box next to the "restart" radio button. The drop-down allows you to select the kernel image that is to be used when rebooting the system. The list of images is created by querying the Lilo map file.

`LiloCommand`

- The location of the Lilo binary (default: `/sbin/lilo`).

`LiloMap`

- The location of the Lilo map file. The map file is maintained by Lilo and contains a list of kernels (versions of the operating system) to boot (default: `/boot/map`).

## Configuring your system to use &kdm;

This chapter assumes that your system is already configured to run the X Window System, and that you only need to reconfigure it to allow graphical login.

### Setting up &kdm;

The fundamental thing that controls whether your computer boots to a terminal prompt (console mode) or a graphical login prompt is the default runlevel. The runlevel is set by the program /sbin/init under the control of the configuration file `/etc/inittab`. The default runlevels used by different Unix systems (and different Linux distributions) vary, but if you look at `/etc/inittab` the start of it should be something like this:

    # Default runlevel. The runlevels used by RHS are:
    # 0 - halt (Do NOT set initdefault to this)
    # 1 - Single user mode
    # 2 - Multiuser, without NFS
    # 3 - Full multiuser mode
    # 4 - unused
    # 5 - X11
    # 6 - reboot (Do NOT set initdefault to this)

    id:3:initdefault:

All but the last line of this extract are comments. The comments show that runlevel 5 is used for X11 and that runlevel 3 is used for multi-user mode without X11 (console mode). The final line specifies that the default runlevel of the system is 3 (console mode). If your system currently uses graphical login (for example, using xdm) its default runlevel will match the runlevel specified for X11.

The runlevel with graphical login (xdm) for some common Linux distributions are:

- 5 for Red Hat 3.x and later, and for Mandrake

- 4 for Slackware

- 3 for S.u.S.E. 4.x and 5.x

The first step in configuring your system is to ensure that you can start &kdm; from the command line. Once this is working, you can change your system configuration so that &kdm; starts automatically each time you reboot your system.

To test &kdm;, you must first bring your system to a runlevel that doesn't run xdm. To do so, issue a command like this:

    /sbin/init 3

Instead of the number "`3`" you should specify the appropriate runlevel for console mode on your system.

Next you need to locate your xdm configuration directory; normally `/etc/X11/xdm/` or `/usr/X11R6/lib/X11/xdm/`. The configuration directory contains the file `Xsetup_0`. If you build &kdm; from source code and the `configure` step is unable to find this directory, it will install a new version of `Xsetup_0` from a template file in the &kdm; source tree. You can include the line:

    kdmdesktop

In your file to display some nice backgrounds (pictures and background colors). (I'm not sure if this still works; it is certainly not required). If your `KDEDIR` is not `/opt/kde` you may have to change the path to `kdmdesktop`.

If your system uses Pluggable Authentication Modules (PAM), which is normal with recent Red Hat and Mandrake systems, you should check that your PAM configuration permits login through the service named `xdm`. If you previously used xdm successfully, you should not need to make any changes to your PAM configuration in order to use &kdm;. `/etc/pam.conf` or `/etc/pam.d/xdm`. Information on configuring PAM is beyond the scope of this handbook, but PAM comes with comprehensive documentation (try looking in `/usr/doc/pam*/html`).

Now it's time for you to test &kdm; by issuing the following command:

    kdm -nodaemon

If you get a &kdm; login box and you are able to log in, things are going well. The main thing that can go wrong here is that the run-time linker might not find the shared Qt or KDE libraries. If you have a binary distribution of the KDE libraries, make sure &kdm; is installed where the libraries believe kde is installed (usually `/opt/kde/bin`) and try setting some environment variables to point to your KDE and Qt libraries. For example:

    export
    KDEDIR=/opt/kde
    export
    QTDIR=/usr/lib/qt2
    export
    PATH=$KDEDIR/bin:$QTDIR/bin:$PATH
    export
    LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib

If you are still unsuccessful, try starting xdm instead, to make sure that you are not suffering from a more serious X configuration problem.

When you are able to start &kdm; successfully, you can start to replace xdm by &kdm;. Again, this is distribution-dependent.

- For Redhat, edit `/etc/inittab`, look for the string xdm and replace it with &kdm; (including all paths).

- For Mandrake, the X11 runlevel in `/etc/inittab` invokes the shell script `/etc/X11/prefdm`, which is set up to select from amongst several display managers, including &kdm;. Make sure that all the paths are correct for your installation.

- For S.u.S.E, edit `/sbin/init.d/xdm` to add a first line:

      . /etc/rc.config
      DISPLAYMANAGER=kdm
      export DISPLAYMANAGER

- Most other distributions are a variation of one of these.

If you don't like changing `inittab`, an alternative is to rename `xdm` to `xdm.bak` and make `xdm` a symbolic link to &kdm;.

At this stage, you can test &kdm; again by bringing your system to the runlevel that should now run &kdm;. To do so, issue a command like this:

    /sbin/init 5

Instead of the number "`5`" you should specify the appropriate runlevel for running X11 on your system.

The final step is to edit the `initdefault` entry in `/etc/inittab` to specify the appropriate runlevel for X11.

Before you make this change, ensure that you have a way to reboot your system if a problem occurs. This might be a "rescue" floppy-disk provided by your operating system distribution or a specially-designed "rescue" floppy-disk, such as `tomsrtbt`. Ignore this advice at your peril.

When you reboot your system, you should end up with the graphical &kdm; login box.

If this step is unsuccessful the most likely problem is that the environment used at boot time differs from the environment that you used for testing at the command line. Check files like `/etc/X11/xdm/Xsetup_0` (and any scripts that it invokes) to make sure that your path is not being changed without your knowledge. If you are trying to get two versions of KDE to co-exist, be particularly careful that the settings you use for your `PATH` and `LD_LIBRARY_PATH` environent variables are consistent, and that the startup scripts are not over-riding them in some way.

### Supporting multiple window managers

The main dialogue box for &kdm; includes a "session type" drop-down box, which allows you to select a window manager to use for your session. This chapter describes the changes that you must make to your configuration files in order to support this feature.

The options that appear in the "session type" drop-down box are configured by entries in the `KDM` section of `kdmrc`.

When you log in using &kdm;, the shell script `Xsession` is executed. The session type that you select is passed as a command-line argument. (`Xsession` can be found in `/etc/X11/xdm/` for Redhat and Mandrake, and in `/usr/X11R6/lib/X11/xdm/` for S.u.S.E.). Whilst debugging, you might find it helpful to add this line to `Xsession`:

    echo "$0 || $1 || $2" > $HOME/.Xsession_args

How you proceed now depends upon how your system usually starts up window managers. Here are two different approaches, with examples of the changes that you must make:

- The window manager is started by commands within `Xsession`. In this case, you can add a case statement to start the appropriate window manager. Linux Mandrake uses this approach; here is an extract from `Xsession`:

      # now, we see if xdm/gdm/kdm has asked for a specific environment
      case $# in
      1)
          case $1 in
              kde)
              source /opt/kde2/bin/kde1
              exec startkde
              ;;
              kde2)
              source /opt/kde2/bin/kde2
              exec startkde
              ;;
          	failsafe)
      	exec xterm -geometry 80x24-0-0
      	;;
      	default)
      	;;
      	*)
      	exec /bin/sh -c "$(/usr/sbin/chksession -x=$1)"
      	;;
           esac
      esac

- The window manager is started by another script that is invoked by `Xsession`. In this case you must ensure that the parameter passed to `Xsession` is passed on to that other script. For example, if the window manager is started like this:

      exec $startup

  you would need to change it to:

      exec $startup $@

  Having made this change, you must trace your way through the startup to find the place where the window manager is started. One approach uses `xinitrc` to start the window manager; this allows a system-wide file `/etc/X11/xinit/xinitrc` or a user-specific file `$HOME/.xinitrc` to be used. If you edit `$HOME/.xinitrc`, you may want to save a copy in `/etc/skel`, so that it will be automatically generated in every user account you create from now on. Here is an example `xinitrc` for a system using this approach:

      #!/bin/bash
      #
      # .xsession/.xinitrc
      #
      # choose a window manager
      #

      defaultwm=kde
      #set the window manager to $1 if it was supplied
      windowmgr=${1:-$defaultwm}

      #start the respective window managers
      case ${windowmgr} in
        kde|kwm|kdestart)
      	WINDOWMANAGER=startkde
      	;;
        fvwm|fvwm2)
      	WINDOWMANAGER=fvwm2
      	;;

        fvwm95)
      	WINDOWMANAGER=fvwm95
      	;;

        *)    WINDOWMANAGER=windowmgr   # default for unknown wm's

      esac

      #
      # load resources
      #

      if [ -f /usr/X11R6/lib/X11/Xmodmap ]; then
          xmodmap /usr/X11R6/lib/X11/Xmodmap
      fi

      if [ -f ~/.Xmodmap ]; then
          xmodmap ~/.Xmodmap
      fi

      if [ -f ~/.Xdefaults ]; then
          xrdb -merge ~/.Xdefaults
      fi

      if [ -f ~/.Xresources ]; then
          xrdb -merge ~/.Xresources
      fi
      #
      # finally start the window manager
      #
      exec $WINDOWMANAGER

## Building and Installing kdm

&kdm; is part of the KDE project. The various component parts of the KDE project are broken into sections, called packages. &kdm; is part of the package called kdebase. You can get KDE source code from various Linux and BSD distribution CDs, or by download from www.kde.org or its mirrors. If you have an out-of-date source code tree, you can use one of the KDE cvsup servers to bring it up-to-date whilst using minimal network bandwidth.

Before building kdebase, you must have built and installed (in this order) version 2 of the qt library and the KDE packages kde-qt-addon, kdesupport and kdelibs.

In order to build any of the above, you must already have the X Window System installed, together with a C++ compiler and the GNU configuration tools configure, automake and autoconf.

If the last few paragraphs seemed like a foreign language, then either you have strayed into an Inappropriate Area of this handbook, or you are about to undergo a Great Learning Experience.

If you managed to satisfy all of the prerequisites, you are unlikely to have any problems with building and installing kdebase. &kdm; is installed in your "`$KDEDIR/bin`" directory.

`make `install`` will overwrite your previous `kdmrc`.

## Other sources of information

Since &kdm; is descended from xdm, the xdm man page may provide useful background information. For X-related problems try the man pages X and startx. If you have questions about &kdm; that aren't answered by this handbook, take advantage of the fact the &kdm; is provided under the terms of the GNUgnu> Public License: look at the source code.

## Credits and License

&kdm; is derived from, and includes code from, xdm.

&kdm; 0.1 was written by Matthias Ettrich. All later versions were written by Steffen Hansen.

Xdm is copyright (c) 1990, X Consortium.

Other parts of the &kdm; code are copyright by the authors, and licensed under the terms of the GNU GPL. Anyone is allowed to change &kdm; and redistribute the result as long as the names of the authors are mentioned.

&kdm; requires the Qt library, which is copyright Troll Tech AS.

Documentation contributors:

- Documentation written by Steffen Hansen stefh@dit.ou.dk

- Documentation extended by Gregor Zumsteinzumstein@ssd.ethz.ch. Last update 1998/07/09

- Documentation revised for KDE2 by Neal Crooknac@forth.org. Last update 2000/07/06

Documentation copyright Steffen Hansen, Gregor Zumstein and Neal Crook.

&underFDL; &underGPL;