path: root/doc/en/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY klamav "<application>KlamAV</application>">
  <!ENTITY klamav_version "0.47">
  <!ENTITY kappname "&klamav;">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &klamav; Handbook</title>

<authorgroup>

<author>
<firstname>Philippe</firstname>
<surname>Mavridis</surname>
<affiliation>
<address><email>mavridisf@gmail.com</email></address>
</affiliation>
</author>

<othercredit role="developer">
<firstname>Robert</firstname>
<surname>Hogan</surname>
<affiliation>
<address><email>robert@roberthogan.net</email></address>
</affiliation>
<contrib>Original Developer</contrib>
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2020</year>
<year>2021</year>
<holder>The Trinity Desktop project</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2021-03-04</date>
<releaseinfo>&klamav_version;</releaseinfo>

<abstract>
<para>
&klamav; is a sophisticated anti-virus manager for ClamAV.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>KlamAV</keyword>
<keyword>ClamAV</keyword>
<keyword>Freshklam</keyword>
<keyword>Klamonacc</keyword>
<keyword>anti-virus</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>
<para>
&klamav; is an anti-virus manager for the Trinity Desktop Environment.
</para>

<para>
It is an advanced front-end to the Clam Anti-Virus toolkit with a lot of useful
features: scan scheduling, on-access scanning, KMail protection, quarantine
management, automatic database updates and even a Virus Browser to do your virus
research.
</para>

<screenshot>
<screeninfo>The main window of &klamav;</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="main.png" format="PNG"/>
    </imageobject>
  </mediaobject>
</screenshot>
</chapter>

<chapter id="using-klamav">
<title>Using &klamav;</title>

<para>
The main window of &klamav; consists of tabs. Each tab has its own function and
most of them can be closed if the user does not need them.
</para>

<para>
Closing a tab disables it. This means that the next time &klamav; starts up,
this tab will remain closed. You can close a tab either from its right-click
context menu or through the <menuchoice><guimenu>Tabs</guimenu></menuchoice>
menu on the top. You can use this menu to re-open any tabs you closed.
</para>

<sect1 id="welcome-tab">
<title>Welcome tab</title>

<para>
This is probably the first tab that the user sees when they launch &klamav;.
It includes an overview of the &klamav; features.
</para>

<para>
This tab has no useful functionality yet, so it can be safely disabled.
</para>
</sect1>

<sect1 id="scan-tab">
<title>Scan tab</title>

<para>
This tab contains the scan manager. From here you can launch and control any
of your &klamav; scans. This tab cannot be closed.
</para>

<para>
By default the manager only contains the tab "Launcher". New scans and their
results are shown in their own separate tabs. These tabs can be managed in the
same fashion as the tabs of the main window.
</para>

<para>
In the "Launcher" tab you can set the directories you want to scan and control
some scanning options.
</para>

<para>
You can select what to do when a virus or a suspicious file is found. The
default is to ask you whether you want to put that file in quarantine or not.
</para>

<para>
Checking the "Scan Folders Recursively" checkbox enables scanning of the
selected folders' subdirectories.
</para>

<para>
The "Schedule" button permits to schedule a scan on the selected directories
on a specific schedule.
</para>

<para>
The "Options" button launches the general Options dialog. This option is also
accessible from the <menuchoice><guimenu>Scanner</guimenu></menuchoice> menu.
</para>

<para>
The three buttons on the top right (Scan, Stop and Close) control scans. When
you choose the directories you want and press "Scan", a new tab will be created
in which you can see the progress of the scan and, when the scan ends, its
results. You can run several scans simultaneously (although this might have an
effect on the system's performance).
</para>

<para>
If you want to end a scan before it completes, use the "Stop" button. Closing
the tab also terminates the associated scan. You cannot close &klamav; while at
least one scan is active.
</para>

</sect1>

<sect1 id="update-tab">
<title>Update tab</title>

<para>
This tab permits you to keep your signature databases up-to-date. You can
control all the options related to database updates from this tab. This tab
cannot be closed. You cannot close &klamav; while this feature is active.
</para>

<para>
In the Virus Database Directory section you can set the folder where you want
your personal copy of ClamAV's signature databases stored. It must be a folder
you have access to.
</para>

<para>
The next section permits you to set up Proxy information for use with Freshklam.
</para>

<para>
Checking the "Update Virus Database Automatically" checkbox enables auto-updates
for this user. You can set how many times a day you want Freshklam to check for
updates.
</para>

<para>
The buttons "Update" and "Cancel" allow you to start/stop the update process
manually.
</para>

</sect1>

<sect1 id="quarantine-tab">
<title>Quarantine tab</title>

<para>
This tab permits you to see which files have been quarantined by &klamav;, delete
them or restore them.
</para>

<para>
The Quarantine Directory section allows you to set the folder where you want
quarantined suspicious files to be stored. It must be a folder you have access
to. The stored files lose their original permission information.
</para>

<para>
The "Contents of Quarantine" section lists the files which are currently stored
in the Quarantine directory. To see the latest additions you might need to
refresh this list, by pressing the "Refresh" button. You can use the "Restore"
and "Delete" buttons to decide on the fate of the quarantined files.
</para>

<para>
The "Quarantine History" section lists the names of files which have once been
quarantined, but which you have since chosen to delete.
</para>
</sect1>

<sect1 id="dbviewer-tab">
<title>Virus Browser tab</title>

<para>
This tab contains the Virus Browser, a tool which allows you to search for
information related to any virus in the ClamAV signature databases on the
Internet.
</para>

<para>
As the Virus Browser deals with a big amount of virus signatures, extracting
them may take some time. Thus, this tab may take a lot of time to load on an
average machine.
</para>

<para>
The left panel contains the name of every virus known to ClamAV, in alphabetical
order, while the right panel contains an embedded web-browser. The web-browser
has tabs, so you can inspect mulitple viruses at once. Common web-browser
actions, like "Back" and "Forward" buttons, are accessible from the right-click
context menu. The web-browser's tabs can be managed in the same fashion as the
tabs of the main window.
</para>

<para>
To inspect a virus, right-click on its name and select a search engine. The same
right-click menu is also accessible from both scan results in the "Scan" tab and
the Quarantine tab. In this case, the Virus Browser tab is automatically shown.
</para>

</sect1>

<sect1 id="events-tab">
<title>Events tab</title>

<para>
This tab contains the a detailed event log for &klamav; and its related parts
(Freshklam, KlamOnAcc).
</para>

<para>
You can filter entries by specifying event type and time span from the drop-down
menus. You can also search through the events by using the search box above the
list.
</para>

<para>
You can configure the events which are written to the events log in the Options
dialog. By pressing the "Options" button, the corresponding section of this
dialog will be shown.
</para>

</sect1>
</chapter>

<chapter id="commands">
<title>Commands Reference</title>

<sect1 id="menu-scanner">
<title>The <guimenu>Scanner</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
</shortcut>
<guimenu>Scanner</guimenu>
<guimenuitem>Scan File...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Open a file</action> to scan with &klamav;.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Scanner</guimenu>
<guimenuitem>Scan Directory...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Open a directory</action> to scan with &klamav;.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Scanner</guimenu>
<guimenuitem>Schedule scan...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Schedule</action> a repeated scan at a specified time.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Scanner</guimenu>
<guimenuitem>Options...</guimenuitem>
</menuchoice></term>
<listitem><para>Launch the <action>Options</action> dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Scanner</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Close</action> &klamav;.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="menu-tabs">
<title>The <guimenu>Tabs</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Tabs</guimenu>
<guimenuitem>Show Welcome tab</guimenuitem>
</menuchoice></term>
<listitem><para>Show/hide the Welcome tab.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tabs</guimenu>
<guimenuitem>Show Quarantine tab</guimenuitem>
</menuchoice></term>
<listitem><para>Show/hide the Quarantine tab.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tabs</guimenu>
<guimenuitem>Show Virus Browser tab</guimenuitem>
</menuchoice></term>
<listitem><para>Show/hide the Virus Browser tab.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tabs</guimenu>
<guimenuitem>Show Events tab</guimenuitem>
</menuchoice></term>
<listitem><para>Show/hide the Events tab.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="menu-help">
<title>The <guimenu>Help</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul"><keycap>F1</keycap></keycombo>
</shortcut>
<guimenu>Help</guimenu>
<guimenuitem>The &klamav; Handbook</guimenuitem>
</menuchoice></term>
<listitem><para>Invokes the TDE Help System starting at the &klamav; help pages (this document).</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu>
<guimenuitem>Report Bug/Request Enhancement...</guimenuitem>
</menuchoice></term>
<listitem><para>Opens the Bug report dialog where you can report a bug or request a “wishlist” feature.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu>
<guimenuitem>Switch Application Language...</guimenuitem>
</menuchoice></term>
<listitem><para>Select the language which &klamav; will use.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu>
<guimenuitem>About &klamav;</guimenuitem>
</menuchoice></term>
<listitem><para>This will display version and author information.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu>
<guimenuitem>About TDE</guimenuitem>
</menuchoice></term>
<listitem><para>This displays the TDE version and other basic information.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

</chapter>


<chapter id="options-dialog">
<title>Options dialog</title>

<para>
The Options dialog contains important settings which affect different aspects of
&klamav;.
</para>

<screenshot>
<screeninfo>The Options dialog</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="opts.png" format="PNG"/>
    </imageobject>
  </mediaobject>
</screenshot>

<sect1 id="options-backend">
<title>The Backend section</title>

<para>
Here you can select the backend that &klamav; will use for its scans. Two backends
are available.
</para>

<para>
The default option is "Standalone scanner", which uses the 'clamscan' command to
scan files and directories. It has the advantage of being the most simple one to
set up and the most customizable option of the two.
</para>

<para>
The other option is "ClamAV daemon", which uses the 'clamdscan' and the 'clamd'
daemon to scan files and directories. It depends on a running 'clamd' daemon,
but the scans overall start faster, as the virus signatures have already been
loaded by the ClamAV daemon. When using this option, most settings depend on the
configuration of the daemon and thus cannot be configured through &klamav;.
</para>

<para>
The Multiscan feature (available when "ClamAV daemon" is set as backend) makes
clamd scan the contents of a directory in parallel using available threads.
</para>
</sect1>

<sect1 id="options-archives">
<title>The Archives section</title>

<para>
Here you can configure everything related to scanning archive files.
</para>

<para>
You can disable scanning of archives by unchecking the "Scan Archives"
checkbox. According to ClamAV's documentation: "If you turn off this option,
the original files will still be scanned, but without unpacking and additional
processing".
</para>

<para>
In the "Archive Limits" section you can impose some custom limits on archive
scanning. Limits can be imposed on extracted file count, file size and archive
recursion level.
</para>
</sect1>

<sect1 id="options-email">
<title>The E-Mail Protection section</title>

<para>
Here you can configure your e-mail client to scan incoming and outgoing files
with Klammail. Currently available clients are KMail and Evolution (untested).
</para>

<para>
You choose the preferred e-mail client from the drop-down list. Then, you can
press the "Tell me how to do it" button to get the appropriate instructions.
</para>

<para>
For KMail, you can also press the "Configure Automatically" button to let &klamav;
do it for you.
</para>
</sect1>

<sect1 id="options-filetypes">
<title>The File Types section</title>

<para>
Here you can configure how different types of files will be treated by &klamav;.
</para>

<para>
The "Exclude Quarantine Directory" option is on by default. You might want to
keep this option on in order to prevent false positives.
</para>

<para>
Options marked red are related to how &klamav; handles suspicious files and
detected viruses.
</para>

<para>
All the other options enable/disable additional parsing of each file type. As
the documentation has it, the original files are still scanned, but without
decoding and additional processing.
</para>
</sect1>

<sect1 id="options-klamonacc">
<title>The On-Access Scanner section</title>

<para>
This sections allows you to configure your on-access file scanner.
</para>

<para>
Currently, this feature is experimental and may cause freezes and considerably
lower performance. Use with care. You cannot close &klamav; while the on-access
scanner is active.
</para>

<para>
You can enable this feature using the "Enable On-Access Scanner" checkbox.
This feature depends on a running instance of the ClamAV daemon, 'clamd'
(but not on the chosen scanning backend).
</para>

<para>
The on-access scanner scans files as soon as you or the system access them. If
a suspicious file is detected, then access to the file is prevented. Extra
checks can be enabled by checking the "Scan Files/Directories When They Are
Created or Moved" checkbox.
</para>

<para>
The "Exclude TDE Configuration Directory" is currently unavailable due to a
possible bug in ClamAV.
</para>

<para>
You can set a limit on the size of scanned files by setting a value for the
"Max File Size" field.
</para>

<para>
Before you can enable the on-access scanner, you should set the directories
which &klamav; will watch for activity. To do this, press the "Set up Directories
to Watch" button.
</para>

<para>
After you have enabled on-access scanning, you can start/stop the scanner daemon
manually through the system tray icon of &klamav;.
</para>
</sect1>

<sect1 id="options-events">
<title>The Event Logging section</title>

<para>
Here you can configure how the event logging feature works.
</para>

<para>
You can change the amount of days &klamav; will wait in order to purge old entries
from its log by setting the "Expire events after..." field to a value of your
preference.
</para>

<para>
You can also configure the events that &klamav; will keep track of and log by
checking/unchecking the appropriate checkboxes.
</para>
</sect1>

</chapter>

<chapter id="tray-icon">
<title>System Tray Icon</title>

<para>
The system tray icon indicates the state of &klamav; and allows you to start/stop
some &klamav; services, notably Auto-Updates and On-Access Scanner (this might be
useful when you want to quit &klamav; while one of these features is active).
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_on_acc_disabled.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that &klamav; is open and the on-access
scanner is inactive.
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_on_acc_enabled.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that the on-access scanner is active.
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_scanning.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that one or more scans are active.
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_scan_safe.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that a scan has finished and no threats
have been found.
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_scan_found.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that a scan has finished and some viruses
or suspicious files have been detected.
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_quarantining.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that some detected files are being put into
quarantine.
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_error.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that an error has occured.
</para>

<para>
<guiicon><inlinemediaobject>
    <imageobject>
      <imagedata fileref="klamav_update_required.png" format="PNG"/>
    </imageobject>
</inlinemediaobject></guiicon>means that there is a newer version of ClamAV and
you should update.
</para>

</chapter>

<chapter id="credits">
<title>Credits and License</title>

<itemizedlist>
<title>
&klamav; &klamav_version;
</title>

<listitem>
<para>
Program copyright 2004-2006 Robert Hogan <email>robert&#64;roberthogan&#46;net</email>
</para>
<para>
and 2020-2021 The Trinity Desktop project
</para>
</listitem>

<listitem>
<para>
Documentation copyright 2021 Mavridis Philippe <email>mavridisf@gmail.com</email>
</para>
</listitem>

<listitem>
<para>
Icons by Maarten van Gent (since version 0.45)
</para>
</listitem>
</itemizedlist>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;              <!-- FDL: do not remove -->
&underGPL;              <!-- GPL License -->

</chapter>

&documentation.index;
</book>