2
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
4
<!ENTITY kappname "&ksysguard;">
5
<!ENTITY package "kdebase">
6
<!ENTITY % addindex "IGNORE">
7
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
10
<book lang="&language;">
12
<title>The &ksysguard; Handbook</title>
16
&Chris.Schlaeger;&Chris.Schlaeger.mail;
19
<othercredit role="developer">
20
&John.Tapsell; &John.Tapsell.mail;
21
<!-- <contrib>Developer</contrib> -->
24
<othercredit role="developer">
25
&Chris.Schlaeger;&Chris.Schlaeger.mail;
26
<!-- <contrib>Developer</contrib> -->
29
<othercredit role="developer">
30
&Tobias.Koenig;&Tobias.Koenig.mail;
31
<!-- <contrib>Developer</contrib> -->
34
<!-- TRANS:ROLES_OF_TRANSLATORS -->
39
<holder>&Chris.Schlaeger;</holder>
42
<legalnotice>&FDLNotice;</legalnotice>
44
<date>2010-10-24</date>
45
<releaseinfo>&kde; 4.5</releaseinfo>
47
<abstract><para>&ksysguard; is a network enabled task and system monitor
48
application.</para></abstract>
51
<keyword>KDE</keyword>
52
<keyword>KSysGuard</keyword>
53
<keyword>process monitor</keyword>
54
<keyword>performance monitor</keyword>
55
<keyword>system monitor</keyword>
56
<keyword>top</keyword>
61
<chapter id="introduction">
62
<title>Introduction</title>
64
<para>&ksysguard; is the &kde; Task and Performance Monitor.
68
a client/server architecture that allows monitoring of local as well as remote
69
hosts. The graphical front end uses so-called sensors to retrieve the
70
information it displays. A sensor can return simple values or more complex
71
information like tables. For each type of information, one or more displays are
72
provided. Displays are organized in worksheets that can be saved and loaded
73
independently from each other. So, &ksysguard; is not only a simple task manager
74
but also a very powerful tool to control large server farms.</para>
78
<chapter id="usingtheksysguard">
79
<title>Using &ksysguard;</title>
81
<sect1 id="getting-started">
82
<title>Getting started</title>
84
<para>&ksysguard; can be started from the application launcher menu, using the entry
85
<guimenuitem>System Monitor</guimenuitem> in the <menuchoice>
86
<guimenu>Applications</guimenu><guisubmenu>System</guisubmenu></menuchoice> menu. Alternatively, you
87
can start it by typing <command>ksysguard</command> in a terminal.</para>
89
<para>The &ksysguard; main window consists of a menu bar, an optional tool bar
90
and status bar, and the work space. Custom worksheets will also show the sensor
94
<para>Download, Save, Import tabs</para>
97
By default &ksysguard; shows two worksheets: <guilabel>Process Table</guilabel>
98
and <guilabel>System Load</guilabel>. The <guilabel>Process Table</guilabel>
99
lists the running processes and lets the user control them.
100
Multiple processes can be selected and controlled at once.
101
The <guilabel>System Load</guilabel> worksheet shows graphs of system utilization:
102
<guilabel>CPU History</guilabel>, <guilabel>Memory and Swap History</guilabel>,
103
and the <guilabel>Network History</guilabel>.
106
<para>This default setup is sufficient enough for an inexperienced user to do
107
some system management. An experienced user or even a system administrator of a
108
large computer lab has different needs. To address a wide range of users,
110
is highly flexible.</para>
113
<sect1 id="process-controller">
114
<title>Process Table</title>
116
<para>The Process Table gives you a list of processes on your
117
system. The list can be sorted by each column. Just press the left
118
mouse button at the head of the column. </para>
120
<para>Use the <guilabel>What's This</guilabel> help for the columns titles
121
to get additional information about the value displayed here.</para>
123
<para>In the context menu of a process in the list view you find additional actions
124
like changing the priority, sending signals to the process, switching to the
125
application window, showing detailed memory information and killing the process.</para>
127
<para>The list shows the following information about each process. Please note
128
that not all properties are available on every operating system.</para>
131
<title>Default Columns in the Process Table</title>
135
<entry><guilabel>Name</guilabel></entry>
136
<entry>The name of the executable that started the process</entry>
139
<entry><guilabel>Username</guilabel></entry>
140
<entry>The user who owns this process</entry>
143
<entry><guilabel>CPU %</guilabel></entry>
144
<entry>The current total CPU usage of the process, divided by the number of
145
processor cores in the machine</entry>
148
<entry><guilabel>Memory</guilabel></entry>
149
<entry><para>This is the amount of real physical memory that this process is using by
150
itself, and approximates the Private memory usage of the process.</para>
151
<para>It does not include any swapped out memory, nor the code size of its shared
153
<para>This is often the most useful figure to judge the memory use
154
of a program.</para></entry>
157
<entry><guilabel>Shared Mem</guilabel></entry>
158
<entry>This is approximately the amount of real physical memory that this
159
process's shared libraries are using. This memory is shared among all
160
processes that use this library</entry>
167
<title>Additional Columns in the Process Table</title>
171
<entry><guilabel>PID</guilabel></entry>
172
<entry>The unique Process <abbrev>ID</abbrev> that identifies this process</entry>
175
<entry><guilabel>TTY</guilabel></entry>
176
<entry>The controlling terminal on which this process is running</entry>
179
<entry><guilabel>Niceness</guilabel></entry>
180
<entry>The priority with which this process is being run. For the normal scheduler,
181
this ranges from 19 (very nice, least priority) to -19 (top priority)</entry>
184
<entry><guilabel>CPU Time</guilabel></entry>
185
<entry>The total user and system time that this process has been running for,
186
displayed as minutes:seconds</entry>
189
<entry><guilabel>IO Read</guilabel></entry>
190
<entry>The number of bytes read. The <guilabel>Display Units</guilabel>
191
and the <guilabel>Displayed Information</guilabel> can be changed using
192
the context menu of this column header</entry>
195
<entry><guilabel>IO Write</guilabel></entry>
196
<entry>The number of bytes written. The <guilabel>Display Units</guilabel>
197
and the <guilabel>Displayed Information</guilabel> can be changed using
198
the context menu of this column header</entry>
201
<entry><guilabel>Virtual Size</guilabel></entry>
202
<entry>This is the amount of virtual memory space that the process is using,
203
included shared libraries, graphics memory, files on disk, and so on. This
204
number is almost meaningless. Use the context menu to select the
205
<guilabel>Display Units</guilabel></entry>
208
<entry><guilabel>Command</guilabel></entry>
209
<entry>The command with which this process was launched</entry>
215
<para>At the top of the table you find three controls which will be described now
216
from left to right.</para>
218
<sect2 id="thekillbutton">
219
<title>End Processes</title>
221
<para>If you have selected one or more processes you can press the <guibutton>End
222
Process</guibutton> button to kill them. A so called <errorcode>SIGKILL</errorcode>
223
is sent to the processes which causes them to terminate immediately.
224
If these applications still have unsaved data this data
225
will be lost. So use this button with care.</para>
228
<sect2 id="the-filter-bar">
229
<title>Filter Bar</title>
231
<para>Filter which processes are shown by the text given here. The text can be a
232
partial string match of the <guilabel>Name</guilabel>, <guilabel>Command</guilabel>
233
or <guilabel>Window Title</guilabel> of the process.
234
It can also be a <guilabel>Username</guilabel> or a Process <abbrev>ID</abbrev> number.</para>
238
<sect2 id="the-process-filter">
239
<title>Process Filter</title>
241
<para>The Process Filter can be used to reduce the number of processes displayed
242
in the table. You can filter out processes you are not interested in. Currently
243
you can display <guilabel>All Processes</guilabel> in a flat or tree view, <guilabel>System
244
Processes</guilabel> only, <guilabel>User Processes</guilabel> only, your
245
<guilabel>Own Processes</guilabel> only or <guilabel>Programs Only</guilabel>.</para>
247
<para>The tree view has been designed to show the relationships between the
248
running processes. A process that is started by another process is called the
249
child of that process. A tree is an elegant way to show this parent-child
250
relationship. The <emphasis>init</emphasis> process is the ancestor of all
253
<para>If you are not interested in the children of a particular process you can
254
click on the little box to the left of the parent and the subtree will
255
collapse. Another click on that box will unfold the subtree again.</para>
257
<note><para>You can launch the <guilabel>Process Table</guilabel> from &krunner;
258
using the <guibutton>Show System Activities</guibutton> button or using
259
the global shortcut <keycombo action="simul"> &Ctrl;&Esc;</keycombo> at any time.
260
The process table is displayed in a window titled <guilabel>System Activities</guilabel>.
266
<sect1 id="the-workspace">
267
<title>Work Space</title>
269
<para>The work space is organized as worksheets. Select
270
<guimenuitem>New Tab...</guimenuitem> from the <guimenu>File</guimenu> menu to create a
271
new worksheet. A dialog will appear where you can set the name, the
272
dimension and the update interval of the worksheet. To remove a worksheet
274
<guimenuitem>Close Tab</guimenuitem> from the <guimenu>File</guimenu> menu. Any
275
modifications will be saved to the worksheet file. If a worksheet has
276
never been saved, you will be asked for a file name. Worksheets consist of
278
organized as a grid.</para>
280
<para>Each cell can be filled with a display for one or more sensors. You can
281
fill a cell by dragging a sensor from the sensor browser and dropping it over
282
the cell. If there is more than one type of display available for that type
283
of sensor, a popup menu will appear. You can then select which display you
284
prefer to use. Certain types of displays can display more than one sensor. Add more
285
sensors to a display by dragging them over from the sensor browser and dropping
286
them over the already existing display.</para>
288
<para>Worksheets can be configured by clicking <guimenuitem>Tab Properties</guimenuitem>
289
at the <guimenu>View</guimenu> menu. In the appearing dialog
290
you can set the dimension and the update interval.</para>
291
<!-- TimerSettings.cc not build in 4.4
292
This update interval is
293
used by all displays of the worksheet, which has the <guilabel>use update
294
interval of worksheet</guilabel> set in its timer configuration dialog.</para>
297
<para>The entry <guimenuitem>Configure Style</guimenuitem> of the
298
<guimenu>Settings</guimenu> menu gives you the possibility to configure the
299
global style attributes and apply them to the current active worksheet.</para>
301
<para>Displays can be configured by clicking with the right mouse button on
302
them. A popup menu appear where you can select whether you want to change the
303
properties of that display or remove it from the worksheet.</para>
305
<sect2 id="the-sensor-browser">
306
<title>Sensor Browser</title>
307
<para>The sensor browser exposes &ksysguard;'s advanced functionality. To
308
use it, you must first go to the <guimenu>File</guimenu> menu and create a new worksheet.
309
It is shown whenever a custom worksheet is selected.</para>
310
<para>The sensor browser displays the registered hosts and their sensors in a
311
tree form. Click on the tree handles to open or close a branch. Each sensor
312
monitors a certain system value.</para>
315
<sect2 id="line-graph">
316
<title>Line Graph</title>
318
<para>The line graph prints samples of one or more sensors over time. If,
319
several sensors are displayed, the values are piled in different colors. If
320
the display is large enough a grid will be displayed to show the range of the
321
plotted samples. By default, the automatic range mode is active so the minimum
322
and maximum values will be set automatically. Sometimes you want fixed
323
minimum and maximum values. In that case, you can deactivate automatic range
324
mode and set the values in the properties dialog.</para>
327
<sect2 id="digital-display">
328
<title>Digital Display</title>
330
<para>The multimeter displays the sensor values as a digital meter. In the
331
properties dialog you can specify a lower and upper limit. If the range
332
is exceeded, the display is colored in the alarm color.</para>
335
<sect2 id="bargraph">
336
<title>Bar Graph</title>
338
<para>The bar graph displays the sensor values as dancing bars. In the
339
properties dialog you can specify minimum and maximum values of range and
340
a lower and upper limit. If the range is exceeded, the display is
341
colored in the alarm color.</para>
344
<sect2 id="sensorlogger">
345
<title>Log to a File</title>
347
<para>The sensor logger does not display any values, but logs them in
348
a file with additional date and time information. For each sensor
349
you can specify a lower and upper limit in the properties dialog.
350
If the range is exceeded, the entry of the sensor table is colored in
351
the alarm color.</para>
354
<sect2 id="partition-table">
355
<title>Partition Table</title>
357
<para>The <guilabel>Partition Usage</guilabel> has a special table
358
sensor showing information about all mounted partitions</para>
361
<sect2 id="connectingtootherhosts">
362
<title>Connecting to other hosts</title>
364
<para>To connect to a new host use <guimenuitem>Monitor Remote Machine...</guimenuitem>
365
from the <guimenu>File</guimenu> menu. A dialog box will appear and allows you
366
to enter the name of the host you want to connect to. Below the name you can choose
367
the connection method. The default is <application>ssh</application>, the secure
368
shell. Alternatively the <application>rsh</application>, the remote shell,
369
the daemon mode or a custom command can be used. Click <guibutton>OK</guibutton> to
370
establish the connection. Shortly afterwards the new host will appear in the
371
sensor browser and you can browse the list of sensors.</para>
373
<!--para>To disconnect from a host, select the host in the sensor browser and
374
choose <guimenuitem>???</guimenuitem> from the
375
context menu. If you still have sensors in use, the display
376
frames will be grayed and the displays won't update any longer.</para-->
378
<para>To establish a connection, a program called
379
<application>ksysguardd</application>, that can be started in the following
380
two modes, must be installed on the new host.</para>
384
<term>daemon mode</term>
386
<para>You can start <application>ksysguardd</application> at boot time in
387
<guilabel>Daemon</guilabel> mode by adding <parameter>-d</parameter> as the
388
argument. In this case, you have to select daemon mode at the connection
389
dialog of <application>ksysguard</application>.
390
A disadvantage of this connection type is that you won't be able to kill or
391
renice a process in the <guilabel>Process Table</guilabel> and
392
the data exchange over network won't be encrypted. As a result, daemon
393
mode is not recommended.</para>
397
<term>shell mode</term>
399
<para>In this mode <application>ksysguardd</application> is started at
400
connecting time by <application>ksysguard</application>. To make that possible,
401
its location needs to be included in your <envar>PATH</envar>.
402
Unfortunately the ssh does not source your <filename>.profile</filename> file,
403
so your regular <envar>PATH</envar> setting will not be available.
404
Instead it uses a default <envar>PATH</envar> like
405
<parameter>/bin:/usr/bin</parameter>.
406
Since it is very likely that &kde; is not installed in these folders you need
407
to create or update a file in your home folder. The file is called
408
<filename>environment</filename> and needs to be in a hidden folder called
409
<filename>.ssh</filename>. See the manual page for
410
<application>ssh</application> for more details. The file needs to contain a
411
line similar to:</para>
414
<userinput>PATH=/bin:/usr/bin:/opt/kde/bin</userinput>
417
<para>assuming that <application>ksysguardd</application> can be found under
418
<filename>/opt/kde/bin/ksysguardd</filename>.</para>
420
<tip><para>When using <application>ssh</application> you should make sure that
421
you have your <filename>identity.pub</filename> installed on the remote machine
422
and the host key of the remote machine is already registered on your machine.
423
If you don't set up <filename>identity.pub</filename> correctly, you will be asked
424
for your password every time you start ksysguard.
425
The easiest way to make sure that everything is working is to run <command>ssh <option>remotehost
426
ksysguardd</option></command> in a shell. If you are greeted by
427
<application>ksysguardd</application>, then everything is working correctly
428
and you can type <userinput>quit</userinput> to exit <application>ksysguardd</application>.</para></tip>
433
<note><para>For experts: <application>ksysguardd</application> is a
434
very small program that is only linked against the libc. So it can
435
also be used on machines that do not have a full blown &kde;
436
installed, such as servers. Many major distributions provide a separate
437
<application>ksysguardd</application> package for your convenience.
438
If you choose the custom command option in
439
the host connector you need to specify the complete command to start
440
<application>ksysguardd</application>.</para></note>
444
<!-- This was removed with revision 517573, but how to disconnect then?
445
<sect2 id="disconnecting-hosts">
446
<title>Disconnecting hosts</title>
448
<para>To disconnect from a host, select the host in the sensor browser and
449
choose <guimenuitem>Disconnect Host</guimenuitem> from the
450
<guimenu>File</guimenu> menu. If you still have sensors in use, the display
451
frames will be grayed and the displays won't update any longer.</para>
458
<chapter id="multiple-platforms">
459
<title>Configuring <application>ksysguardd</application></title>
461
<para>The graphical front-end is available on any platform that &kde; runs
462
on. The back-end is at the moment available on the following flavors of
467
<term>&Linux; 2.x</term>
468
<listitem><para> For <application>ksysguardd</application> to work it
469
is necessary to compile the &Linux; Kernel
470
with the <filename>/proc</filename> File system enabled. This is the default
471
setting and most &Linux; Distributions have it already.</para> </listitem>
475
<listitem><para>The <application>ksysguardd</application> program
476
needs to be owned by the <systemitem
477
class="groupname">kmem</systemitem> group and needs to have the setgid
478
bit set.</para></listitem>
481
<term>&Solaris;</term>
482
<listitem><para>To be written</para></listitem>
486
<para>Support for other platforms is in progress. Your help is greatly
490
<chapter id="credits-and-licenses">
491
<title>Credits and Licenses</title>
493
<para>&ksysguard; is currently developed and maintained by &John.Tapsell;
494
&John.Tapsell.mail;. &ksysguard; is a rewrite of
495
<application>KTop</application>, the &kde; 1.x task manager. Several other people
496
have worked on <application>KTop</application>:</para>
499
<listitem><para> A. Sanda <email>alex@darkstar.ping.at</email></para></listitem>
500
<listitem><para> Ralf Mueller <email>ralf@bj-ig.de</email></para></listitem>
501
<listitem><para> &Bernd.Johannes.Wuebben;
502
<email>wuebben@math.cornell.edu</email></para></listitem>
503
<listitem><para> Nicolas Leclercq
504
<email>nicknet@planete.net</email></para></listitem>
507
<para>The porting to other platforms than &Linux; was done by:</para>
510
<listitem><para> FreeBSD: Hans Petter Bieker
511
<email>zerium@traad.lavvu.no</email></para></listitem>
514
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->