README

(Last updated Feb 11, 2007)

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

$ perl clamtk or
$ 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

6. Running ClamTk

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.
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!
Information on items quarantined is available under the "Quarantine" option. This is another safe option, along with the default option.
Scan a file by either clicking the icon (first on the left), or going under "File".
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.
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.
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".

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 your distro's repo 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!

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