README
------
(Last updated June 14, 2008)

1. Important Links

ClamAV		: http://www.clamav.net
ClamTk		: http://freshmeat.net/projects/clamtk/
Dag Wieers	: http://dag.wieers.com
Fedora		: http://fedoraproject.org #for FC ClamAV rpms
Debian		: http://www.debian.org
Gtk2-Perl	: http://gtk2-perl.sourceforge.net
ClamTk FAQ	: http://clamtk.sf.net/faq.html

2. About

ClamTk is a frontend for ClamAV using Gtk2-perl. It is intended to be
an easy to use, lightweight scanner for Linux systems. It has been
ported to Fedora, Debian, RedHat, SuSE, ALT Linux, Ubuntu, CentOS,
Gentoo, Mandriva and FreeBSD.

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

3. GUI

ClamTk started out using the Tk libraries (thus its name). I have
since switched to perl-Gtk2 (or Gtk2-perl, whatever). The Tk version
is still available on sourceforge.net.

I'm also open to a name change, but that seems like too much effort.

4. Cross-distro

RPMs and .debs are available from clamtk.sourceforge.net, as well as
apt and yum repos.
Check rpmfind.net or your local packager for others. The source works
just fine too!

5. Installation

RPMs:
The easiest way to install ClamTk is to use the rpms.
For Fedora Core, Fedora Extras has any necessary dependencies.
As root (or better, use "su -" or "sudo"):
# yum install clamav clamav-update clamav-data clamav-lib
and:
# rpm -Uvh clamtk-*.rpm

To remove clamtk:
# rpm -e clamtk

If you have installed clamtk-kde, then you will have to do this:
# rpm -e clamtk clamtk-kde

SOURCE:
The tarball contains all the sources. You can also launch the perl script
with:
	a. $ perl clamtk
	or
	b. $ chmod +x clamtk
	   $ ./clamtk

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

Or make it available to everyone by copying it to /usr/local/bin or /usr/bin:
As root, type (without the pound '#' sign, of course):
# cp clamtk /usr/local/bin
or
# cp clamtk /usr/bin

DEBs:
# dpkg -i clamtk-*.deb

To remove clamtk:
# dpkg --purge clamtk

or, possibly:
# dpkg --purge clamtk clamtk-kde

To add right-click functionality, you may wish to do the following:

For KDE, as root type the following:
# cp clamtk-kde.desktop /usr/share/apps/konqueror/servicemenus/

For Gnome, as root type the following:
# cp clamtk.desktop /usr/share/applications

Note that if you have installed this program as an rpm or .deb, you probably
do not need to take these steps.

6. Running ClamTk

	a. I would recommend launching ClamTk as root first, if only to 
	   ensure you have the latest virus signatures. The rpm version
	   of clamav insists on root doing this (I'm not complaining;
	   only pointing it out). The update feature is located under "Help"
	   - or you can use "ctrl-U". Since you shouldn't be logging in
	   as root anyway, open up another terminal window (or another tab
	   in the terminal window), type "su -", the root password, and
	   then type "clamtk". You'll notice that the icon next to
	   "Update Signatures" is now green instead of red, indicating
 	   that you can now update the signatures.

	   * NOTE: ClamTk can't find your virus definitions? See the
	   TROUBLESHOOTING section toward the end of this file.

	b. Also consider the options under "Options".
	   By selecting "Save to Log", you can opt to save a log of your
	   scanning. Select "Scan Hidden Files (.*)" to scan those files
	   beginning with a "."). If you'd like to see ALL files appear
	   as scanned, select "Display All Files". If you utilize symoblic
	   links, you can select that option here as well. If you don't know
	   what those are, feel free to skip it. 

	   Note: "Detect Broken Executables" is now enabled by default.

	   Finally, you have the option to have ClamTk automatically
	   quarantine files it believes may be harmful.

	   Note: The automatic "Delete" option has been removed. After
	   scanning, you can still right-click on the file and delete it
	   from there.

	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 icon (first on the left), or
	   going under "File".

	e. Scan a directory by either clicking the icon (second on the left),
	   or going under "File". 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 
	   way ClamTk scans - the speed, that is - 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 Options, select which options you prefer,
	   and click Ctrl-P (or select Save Scan Preferences under View).
	   Then, when you wish to use these options, load them by clicking
	   Ctrl-L (or select Load Scan Preferences under View).

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).
If you want more extensive commandline options, it is recommended that you
use the clamscan binary itself. (Type "man clamscan" at the commandline.)

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. Symbolic Links

ClamTk will scan directories which are symbolically-linked IF the option
"Follow Symbollic Links" is selected. Quarantine and delete options should
work just fine.

However, files which are symbolically-linked will only quarantine or
delete the linked name, NOT the target file (ie., the REAL file). This
is in line with the way 'clamscan --remove' works. I'm not sure how often
this will come up, but here it is.

Note that I will probably remove the symbolic links functionality.
It seems entirely too risky to keep it.

10. Locale/Internationalization

Version 2.20 is the first ClamTk version to offer this. Have time
on your hands and want to contribute? Contact me!

11. 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.

12. 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).

13. Other

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

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 to me.
A new version means it goes up 1. Or .01, whichever. Because I
changed from Tk to Gtk2 I did move the major version number up 
significantly, but that was just to keep them separate.
Just pointing it out.

14. 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.info" -print
  3. find /var -name "daily.cld" -print

  Yes, there are three variations on the definitions...

* 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.

15. Thanks

	* Everyone who has contributed in one way or another to ClamTk -
	  including language assistance and bug notifications
	* 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 to learn Perl (and continuing
	  to do so on a daily basis!)
	* Ksnapshot for making snapshot-taking very easy
  
16. Language contributions

  A big thank you to the following for being so generous with their time!

	* Karel Hudan, Czech (cs_CZ)
        * Jimmy Christensen, Danish (da_DK)
        * Ronny Steiner, German (de_DE)
	* Mariano Rojo, Spanish (es_ES)
        * Alain Bernard, French (fr_FR)
	* David Garcia Rojo, French (fr_FR)
	* Viale Fabrice, French (fr_FR)
	* Román Perez, Galician (gl_ES)
        * Edoardo Tosca, Italian (it_IT)
        * Tobia Fasciati, Italian (it_IT)
	* Alessandro Volturno, Italian (it_IT)
	* Gina C, Korean (ko_KR)
	* Rob van den Berg, Dutch (nl_NL)
	* Robert Tomasik, Polish (pl_PL)
        * Bruno Diniz, Portugese (pt_BR)
	* Veronica B., Romanian (ro_RO)
	* Vitaly Lipatov, Russian (ru_RU)
	* Petter Viklund, Swedish (sv_SE)
        * Tao Wei, Chinese (zh_CN)

dave.nerd AT gmail DOT com