# The &ksysguard; Handbook

Chris
Schlaeger

    cs@kde.org

Chris
Schlaeger

    cs@kde.org

Developer
Lauri
Watts

    vampyr@atconnex.net

Reviewer
2000
Chris Schlaeger
&FDLNotice;
2000-12-14
1.00.00

&ksysguard; is a network enabled task manager and system monitor application, with the additional functionality of top.

KDE
KSysGuard
process monitor
top
ps

## Introduction

&ksysguard; is the KDE Task Manager and Performance Monitor. It features a client server architecture that allows monitoring of local as well as remote hosts. The graphical front end uses so called sensors to retrieve the information it displays. A sensor can return simple values or more complex information like tables. For each type of information one or more displays are provided. Displays are organized in work sheets that can be saved and loaded independantly from each other. So &ksysguard; is not only a simple task manager but also a very powerful tool to control large server farms.

## Using &ksysguard;

### Getting started

&ksysguard; can be started from the start menu, using the entry KDE System Guard in the Systems menu. Alternatively you can start it by typing `ksysguard` in a terminal.

The &ksysguard; main window consists of a menu bar, an optional tool bar and status bar, the sensor browser and the work space. When first started you see your local machine listed as localhost in the sensor browser and 2 pages in the work space area. This is the default setup.

This default setup is sufficient enough for an unexperienced user to do some system management. An experienced user or even a system administrator of a large computer lab has different needs. To address a wide range of users, &ksysguard; is higly flexible.

### The Sensor Browser

The sensor browser displays the registered hosts and their sensors in a tree form. Click on the tree handles to open or close a branch. Each sensor monitors a certain system value.

#### Connecting to other hosts

To connect to a new host user Connect Hosts from the File menu. A dialog box will appear and allows you enter the name of the host you want to connect to. Below the name you can choose the connection method. The default is ssh, the secure shell. Alternatively the rsh, the remote shell, can be used. Click OK to establish the connection. Shortly afterwords the new host will appear in the sensor browser and you can browser the list of sensors.

To establish a connection a program called ksysguardd is started on the new host. This program must be installed on the machine and needs to be included in your `PATH`. Unfortunately the ssh does not source your `.profile` file, so your regular `PATH` setting will not be available. Instead it uses a default `PATH` like `/bin:/usr/bin`. Since KDE is very likely not installed in these directories you need to create or update a file in your home directory. The file is called `environment` and needs to be in a hidden directory called `.ssh`. See the manual page for ssh for more details. The file needs to contain a line like the following:

    PATH=/bin:/usr/bin:/opt/kde2/bin

assuming that ksysguardd can be found under `/opt/kde2/bin/ksysguardd`.

For experts: ksysguardd is a very small program that is only linked against the libc. So it can also be used on machines that do not have a full blown KDE installed such as servers. If you choose the custom command option in the host connector you need to specify the complete command to start ksysguardd.

When using ssh you should make sure that you have your identity.pub installed on the remote machine and the host key of the remote machine is already registered on your machine. The easiest way to check this is to type `ssh `remotehost ksysguardd`` in a shell. If you are greeted by ksysguardd you can type `quit` and everyting is in order.

#### Disconnecting hosts

To disconnect from a host, select the hosts in the sensor browser and choose Disconnect Host from the File menu. In case you still have sensors in use, the display frames will be greyed and the displays wont update any longer.

### The Work Space

The work space is organized as work sheets. Select New from the File menu to create a new work sheet. A dialog will appear where you can set the name and the dimension of the work sheet. To remove a work sheet again, select Close from the File menu. Any modifications will be saved to the work sheet file. In case a work sheet has never been saved you are asked for a file name. Work sheets consist of cells organized as a grid.

Each cell can be filled with a display for one or more sensors. You can fill a cell by dragging a sensor from the sensor browser and dropping it over the cell. In case there is more than one type of display available for that type of sensor, a popup menu will appear. You can then select which display you prefer to use. Certain types of displays can display more than one sensor. Add more sensors to a displays by dragging them over from the sensor browser and dropping them over the already existing display.

Displays can be configured by clicking with the right mouse button on them. A popup menu appear where you can select whether you want to change the properties of that display or remove it from the work sheet.

#### Signal Plotter

The signal plotter prints samples of one or more sensors over time. In case several sensors are displays the values are piled in different colors. If the display is large enough a grid will be displayed to show the range of the plotted samples. If you set the minimum and maximum value in the properties dialog to 0 the plotter will work in automatic range mode. Otherwise the specified values for the range are used.

#### Multimeter

The multimeter displays the sensor values as a digital meter. In the properties dialog you can specify minimum and maximum values. In case the range is execeeded the display is colored in red and a warning box appears.

#### Process Controller

The Process Controller gives you a list of processes on your system. The list can be sorted by each column. Just press the left mouse button over the head of the column.

The list shows the following information about each process. Please note that not all properties are available on every operating system.

PID

  The Process ID. A unique number for each process.

Name

  The name of the executable that started the process.

User ID

  The login name of the user that started the process.

CPU

  The processor load of the process in percent.

Time

  The total computation time of the process so far.

Nice

  The scheduling priority.

Status

  The process status.

Memory

  The total amount of memory (in kBytes) the process uses. This includes shared memory.

Resident

  The amount of physical memory (in kBytes) the process uses.

Shared

  The amount of memory (in kBytes) the process shares with other processes.

Underneath the table you find four buttons which will be described now from left to right.

##### The Tree View

The tree view has been designed to show the relationships between the running processes. A process that is started by another process is called the child of that process. A tree is an elegant way to show this parent-child relationship. The init process is the ancester of all processes.

If you are not interested in the children of a particular process you can click on the little box to the left of the parent and the subtree will collapse. Another click on that box will unfold the subtree again.

##### The Process Filter

The Process Filter can be used to reduce the number of processes displayed in the table. You can filter out processes you are not interested in. Currently you can display all processes, system processes only, user processes only or your processes only.

##### The Pause Button

Select the pause button if you want to halt the automatic update of the process list.

##### The Refresh Button

This button can be used to force an immediate update of the process list.

##### The Kill Button

If you have selected one or more processes you can press the kill button to kill them. A so called SIGKIL is sent to the processes which causes them to terminate immediately. If these applications still have unsaved data this data will be lost. So use this button with care.

## Credits and Licenses

&ksysguard; is currently developed and maintained by Chris Schläger cs@kde.org. &ksysguard; is a rewrite of KTop, the KDE 1.x task manager. Several other people have worked on KTop:

- A. Sanda alex@darkstar.ping.at

- Ralf Mueller ralf@bj-ig.de

- Bernd Johannes Wuebben wuebben@math.cornell.edu

- Nicolas Leclercq nicknet@planete.net

The porting to other platforms than Linux was done by:

- FreeBSD: Hans Petter Bieker <zerium@traad.lavvu.no>

&underFDL; &underGPL;

## Installation

### How to obtain &ksysguard;

&ksysguard; is part of the KDE project http://www.kde.org. &ksysguard; can be found on ftp://ftp.kde.org/pub/kde/, the main ftp site of the KDE project.

### Requirements

In order to successfully compile &ksysguard;, you need the KDE 2.0 and Qt 2.2.x. All required libraries as well as &ksysguard; itself can be found on ftp://ftp.kde.org/pub/kde/.

The graphical front-end is available on any platform that KDE runs on. The back-end is at the moment available on the following flavors of UNIX:

Linux 2.x

  For &ksysguard; to work it is necessary to compile the Linux-Kernel with the `/proc` Filesystem enabled. This is the default setting and most Linux-Distribution have it already.

FreeBSD

  The &ksysguard; program needs to be owned by the kmem group and needs to have the setgid bit set.

Support for other platforms is in preparation. Your help is greatly appreciated.

### Compilation and Installation

In order to compile and install &ksysguard; on your system, type the following in the base directory of the kdeutils distribution:

    % ./configure
    % make
    % make install

Should you run into problems please report them to the KDE mailing lists.