README
------
(Last updated Oct 8, 2011)

1. Important Links

ClamTk FAQ		: http://clamtk.sf.net/faq.html
ClamAV			: http://www.clamav.net
ClamTk			: http://freshmeat.net/projects/clamtk/
				: http://clamtk.sf.net
				: http://clamtk.cvs.sf.net
Gtk2-Perl		: http://gtk2-perl.sourceforge.net
Launchpad ClamTk: https://launchpad.net/clamtk

2. About

ClamTk is a frontend for ClamAV using Gtk2-perl. It is intended to be
an easy to use, light-weight, on-demand scanner for Linux systems. It has been
ported to Fedora, Debian, RedHat, openSUSE, ALT Linux, Ubuntu, CentOS,
Gentoo, Archlinux, Mandriva, PCLinuxOS, Frugalware, FreeBSD, and others.

Although its earliest incarnations date to 2003, it was first uploaded
for distribution in 2004 to a rootshell.be account and finally to
Sourceforge.net in 2005.

3. GUI

ClamTk started out using the Tk libraries (thus its name). In 2005, 
this was changed to perl-Gtk2 (or Gtk2-perl, whatever). The Tk version
is still available on sourceforge.net but has not been updated for
some time now and should not be used.

4. Availability

I always recommend you install ClamTk from official repositories.
Check your distribution first, and always install from trusted sources.

RPMs for Fedora and CentOS are available from clamtk.sourceforge.net,
and its requirements from apt and yum repos.

Check rpmfind.net or your local packager for others. The source works
just fine too, but be warned that version >= 4.00 has gotten more complex
and is no longer just a single script; that is, it may take a slight bit
of tweaking. It is actually much easier to install with package managers.

ClamTk is also available via the official Fedora yum repositories and
Debian/Ubuntu repositories.

5. Installation

RPMs:
The easiest way to install ClamTk is to use the rpms.

First, try "yum install clamtk". If this does not work,
download it and try:

# yum localinstall --nogpgcheck clamtk*.rpm

The "--nogpgcheck" option is necessary since I no longer gpg-sign
the rpms. Note that the Debian/Ubuntu builds are gpg-signed.

To remove clamtk:
# yum erase clamtk

SOURCE:
The tarball contains all the sources. One way to do this on Fedora:
# mkdir -p /usr/share/perl5/ClamTk
# cp lib/*.pm /usr/share/perl5/ClamTk
# chmod +x clamtk
# cp clamtk /usr/local/bin (or /usr/bin)

	EXAMPLES:
	a. $ perl clamtk
	or
	b. $ chmod +x /path/to/clamtk
	   $ /path/to/clamtk

* Note: If you have installed this program as an rpm or .deb, you
do not need to take these steps.

* Note: Did you get errors with this? Check the TROUBLESHOOTING section
at the end.

DEBs:

You should be able to just double-click the .deb file to install it.
This assumes you have permissions to install programs, of course. Your
package manager should grab any necessary dependencies.

By the commandline, you can do this:

# dpkg -i clamtk-*.deb

To remove clamtk:
# dpkg --purge clamtk

6. Running ClamTk

	a. Beginning with version 4.23, ClamTk will automatically
	   search for signatures if you do not have them set already.
	   This way ClamTk should work right out of the box, with no
	   prompting.

	b. Consider the extra scanning options by typing Ctrl-P.
	   By selecting "Keep a record of every scan", you can opt
	   to save a log of your scanning.

	   Select "Scan files beginning with a dot (.*)" to scan
	   those files beginning with a ".". 

	   Select "Scan all files and directories within a directory"
	   for a more thorough scan.

	   The "Enable extra scan settings" option enables the ability
	   to scan for PUA's, or Potentially Unwanted Applications as well as
	   broken executables.

	   By default, ClamTk will avoid scanning files larger than 20MB.
	   To force scanning of these files, check the "Scan files
	   larger than 20 MB" box.

	   Note: The automatic "Delete" and "Quarantine" options have
	   been removed. After scanning, you can still right-click on the
	   file and take actions from there. Be warned that once a file
	   has been deleted, it is gone. There is no recycle bin.

	c. Information on items quarantined is available under the 
	   "Quarantine" option. "Status" will quickly inform you of the
	   number of files you have quarantined. "Maintenance" will
	   allow you to delete quarantined files or, if you believe there
	   is a false positive contained, you can easily move it back to
	   your home directory. You may also empty your quarantine folder
	   with the "Empty Quarantine Folder" options as well.

	d. Scan a file by either clicking the File icon or selecting the
	   option under "Scan".

	e. Scan a directory by either clicking the icon or going under
	   "Scan". Also available is the recursive scan, which
	   will descend to all directories within the selected directory.

	f. You can STOP the scan by clicking the stop button located on the
	   gui toolbar (red circle with the white X). Note that due to the 
	   speed of the scanning, it may not stop immediately; it will
	   continue scanning and displaying files it has already "read"
	   until the stop catches up.

	g. Occasionally, you may wish to have certain options set for
	   certain scans. Under Advanced, select Preferences (or click
	   Ctrl-P. Here you can also set Startup Preferences as well as
	   directories for whitelisting (to not be scanned, that is).

	h. You can also conduct scans of your Home drive easily by clicking
	   the icon or using the option under "Scan".

	* Note: ClamTk no longer follows symlinks.

7. Commandline

ClamTk can run from the commandline, too:

$ clamtk file_to_be_scanned
or
$ clamtk directory_to_be_scanned

However, the main reason for the commandline option (however basic) is
to allow for right-click scanning within your file manager (e.g., Nautilus
or Dolphin).  If you want more extensive commandline options, it is
recommended that you use the clamscan binary itself. (Type 
"man clamscan" at the commandline.) Or, if you know of something useful,
let me know and I can add it as an option.

8. Afterwards

If you've opted to save the results, you can view and delete them by
selecting the "Manage Histories" option under "View".

Clear away the output by clicking the clear icon (looks like a broom) on the
gui toolbar, or select "Clear Output" under "View".

You also have a few options with the files displayed. Click on the file
scanned to select it, then right-click: you should have four options there.

	a. Quarantine this file: This drops the selected file into a
	"quarantined" folder.
	b. Delete this file: Be careful! There's no recycle bin!
	c. Save As: This option is useful if, for example, you wish to
	scan a file downloaded with your browser. Typically, such files
	are moved off to your temp (/tmp) directory and difficult to 
	recover. So, use this to save it elsewhere, such as your
	home directory.
	d. Cancel: Cancels this menu.

9. Quarantine / Maintenance

If you've quarantined files for later examination, you have several options:

	a. Check the Status (Ctrl-S, or Quarantine/Status) - Lets you know
	   how many (if any) files you have quarantined
	b. Empty the quarantine area (Ctrl-E, or Quarantine/Empty) - Just
	   a reminder: there is no recycle bin! Be careful with this, and
	   ensure you wish to delete them.
	c. Maintenance (Ctrl-M, or Quarantine/Maintenance) - Here you have
	   the option to delete or restore files. If ClamTk knows where the
	   file originally was, the file can be put back.

10. Scheduling

As of version 4.18, users can schedule antivirus signature updates
as well as daily scans. Because no cross-distro Perl module is widely
available, this requires the "crontab" program, which is pretty standard.

While you do have the option to scan your entire computer (excluding
the /proc, /sys and /dev directories), you probably only need to
scan your home directory. If you're interested in scanning your entire
system, you're probably going to want a program that scans for signs
of a rootkit instead.  In this case, check out rkhunter or chkrootkit.

To view the results of the scheduled scan, look under "View" and
"Manage Histories".

11. Proxy settings

For those who need to set a proxy for signature updates, a "Proxy
settings" tab is available under Preferences. Most will be fine with
"No Proxy". The "Environment settings" option will look for the
http_proxy setting in %ENV. You can also set it manually with an
IP address or hostname as well as the port number.

12. Locale/Internationalization

Version 2.20 is the first ClamTk version to offer this. Have time
on your hands and want to contribute? See the Launchpad page at
https://launchpad.net/clamtk .

Note that some builds do not account for other than English
languages because they have not yet updated their build/spec files.
A polite email to the respective maintainer may fix this.

13. Limitations/Bugs

Probably a lot. Let me know, please. Ranting on some bulletin board
somewhere on one of dozens of Linux sites will not improve things.
Let me know what you like and dislike!

One of the current issues that hopefully will be resolved is that
ClamAV rpms are not standardized. This isn't my fault (that I'm aware of),
but I feel it adds unnecessary confusion (as opposed to necessary
confusion :). Because of this, multiple builds are needed as opposed to
just one. Fortunately, Debian does not appear to suffer from this.

Also, some distributions require you to manually delete certain
malware - such as the (un)popular right-to-left override stuff.
Hopefully, this is just temporary.

14. Contact 

For feature requests or bugs, it's best to email me. You can also go
to the Sourceforge project page and submit requests/problems there
(http://sourceforge.net/projects/clamtk).

15. Other

As of version 3.10, ClamTk will not scan standard mail directories,
such as .evolution, .mozilla or .thunderbird. This is due to parsing
problems.  If I come up with a smart way of doing that, it will be added.
It will probably have to wait until version 5.x.

Note that "delete" and "quarantine" options have been disabled if
scanning involves the directories "/proc", "/dev", or "/sys". Let
me know if you have suggestions on better or other ways of dealing
with that, or if there are other directories that should be avoided.

Also, please note that version numbers mean absolutely nothing. There
is no rhyme or reason to odd or even numbers, so an odd number does not
mean "unstable".  A new version means it goes up 1 (or, rather, .01).
Because I changed from Tk to Gtk2 I did move the major version number up 
significantly, but that was just to keep them separate.
The version 3.x series became 4.x when there was a major change in
the packaging and processes.
Just pointing it out.

16. Troubleshooting

* Are your signatures up to date, but ClamTk says they're not?

  You probably have more than one virus signature directory. See below
  answer for finding signatures.

* If you are getting an error that ClamTk cannot find your signatures:

  ClamTk is trying to find its virus definitions. Typically these are
  held under /var/lib/clamav or /var/clamav or ... If you are sure these
  files exist, please find their location and send it to me.
  Try the following to determine their location:

  1. find /var -name "daily.cvd" -print
  2. find /var -name "daily.cld" -print

* Are you using the source and you see something like this:
Can't locate Foo/Bar.pm in @INC... (etc, etc).

  This means you are missing some of the dependencies. Try to find
  the dependency through your distribution's repositories, or simply
  go to http://search.cpan.org. I recommend trying your distro's repo
  first. It's more than likely your distribution already packages these
  for easy installation. Depending on your distro, you will likely
  use "yum" or "apt" or some "Update Manager" and the like.

17. Thanks to...

	* Everyone who has contributed in one way or another to ClamTk -
	  including language assistance, bug notifications, and
	  feature requests
	* Dag, without whom rpms would likely not currently exist
	* Muppet and the gtk2-perl folks for their time and effort
	* Perlmonks.org for helping me learn the wonderful Perl language -
	  and continuing to do so on a daily basis!
	* Ksnapshot for making snapshot-taking very easy
  
18. Contributors

  Many people have contributed their time, energy, opinions,
  recommendations and expertise to this software. I cannot thank
  them enough.

  Please see http://clamtk.sf.net/credits.html for a complete listing.

19. Contact

email : dave.nerd AT gmail DOT com
jabber: dave-m AT jabber DOT org
