README
------
(Last updated Sept 6, 2006)

1. Important Links

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

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 Core, Debian, RedHat, SuSE, ALT Linux, Ubuntu,
Gentoo, and Mandriva.

Note that some builds do not account for other than English
languages because they have not yet updated their spec files.

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'll go back to 
maintaining the Tk version if there is a demand for it. There are
advantages and disadvantages to both.

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

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

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" and "Actions".
	   Under "Scan Options" you can opt to save a log of your
	   scanning, show hidden files (those beginning with a "."),
	   and/or show ALL files (typically, only those files which are
   	   infected or otherwise not clean are shown). 

	   Note that "Detect Broken Executables" can be an effective
   	   option. For example, sometimes before ClamAV has a definition
	   for a virus, the virus will still be detected as a broken executable.

	   Under "Actions", you have the choice of having ClamTk
	   just report viruses (the default), quarantine them, or
	   delete them. Be very careful with the "delete" option!
	   As of 2.13, you can right-click on files you've scanned and
 	   delete or quarantine them. This is MUCH safer!

	c. Information on items quarantined is available under the 
	   "Quarantine" option. This is another safe option, along with
	   the default option.

	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.

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.

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

The "Quarantine" option allows you three options: "Status" (if you
currently have anything quarantined); "Maintenance"; and "Empty".
"Maintenance" gives you refined control over the quarantined files: you
may delete individual files or move them back to your home directory. This
is useful if a file is a false positive. "Empty" will clean out the
quarantine directory.

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.

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.

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

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

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

  ClamTk is trying to find daily.cvd and main.cvd. 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 one of the following to determine their location:

  1. locate daily.cvd
  2. find /var -name "daily.cvd" -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 the first option
  first. It's more than likely your distribution already packages these
  in an easy-to-install package.

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!

        * Jimmy Christensen, Danish (da_DK)
        * Ronny Steiner, German (de_DE)
	* Mariano Rojo, Spanish (es_ES)
        * Alain Bernard, French (fr_FR)
        * Edoardo Tosca, Italian (it_IT)
        * Tobia Fasciati, Italian (it_IT)
	* Robert Tomasik, Polish (pl_PL)
        * Bruno Diniz, Portugese (pt_BR)
	* Vitaly Lipatov, Russian (ru_RU)
        * Tao Wei, Chinese (zh_CN)

dave.nerd AT gmail DOT com
