
FIRST OF ALL, DON'T MAIL ME IF YOU SIT BEHIND ONE OF THOSE MAILGATES WHICH USE IP BLACKLISTS! THANKS.

Table of Contents:
-------------------

1.0 Status
2.0 Thanks
3.0 Install
	3.1 Squidclam config
4.0 Performance
5.0 Tempfs
6.0 Common Errors
7.0 FAQ
8.0 Sample squid.conf

Code Status:
-------------

squidclam is a program to scan files served to win32
machines by a squid proxy. 

At the moment squidclam is pretty small, scans files for viruses
and is doing it's job pretty well for me.

If you know what your doing and have some knowledge in C and secure
programing please give it a try and provide some feedback.

If you have comments, questions whatever please let me know also. 

If you like to get an answer, don't use an account with rtbls for spam
"protection" to contact me
And no I won't change my setup to use a smarthost!

Thanks:
--------
to
    the clamav team www.clamav.net for there OSS virus scanner
    the squid team www.squid-cache.org for there HTTP Proxy
    Michael Lang http://www.jackal-net.at/ for the idea.
    Tommaso Di Donato for excessiv testing, debugging, docu.
    Petr Kristof_CZ for debugging and spec file.
    Jakub Schmidtke for his fix for the broken unlink.
    cedric_krier for fixing the close socket and FSIZE bug.
    2nd_change@mail.ru for reading the readme (half) ;)
	Steve-o for unix socket patch


Install:
---------

    - get and install clamav
		since version 0.13 squidclam uses clamd so make sure 
        it's listening for TCP connections
		
    - get and install curl

    - create a tmpfs or ramdisk and mount it at /dev/shm (since 0.17 this is the default location)

    - compile squidclam

        cd squidclam-$RELEASENUM
        ./configure
        cd src
        make
        make install OR just copy the file squidclam to a location you like.
		make DESTDIR=/usr/local/bin install is another option.
        and maybe using checkinstall is a good idea too...

    - configure squid to use squidclam

        add the following to your squid.conf
        "redirect_program /usr/local/bin/squidclam"
        "redirect_children 15"  # make a wise choice

        and this line to your acl list to prevent loops
        "redirector_access deny localhost"

        squid doesn't pass complete ssl urls to the redirector.
        Therefor scanning them is pretty useless add something like the following 
        to avoid this and save bandwidth.
        "acl SSL_ports port 443 563"
        "redirector_access deny SSL_ports"

    - test it at www.eicar.com

    - provide me some feedback to squidclam AT users DoT sourceforge DoT net ;)
      don't use such a braindeath mailer with ip blacklists if you want me to answer.

Squidclam config:
-----------------

	Since version 0.10 there is support for a config file in squidclam.
	Default this is /etc/squidclam.conf. There is a sample.conf file in
	the source tarball where you can get an idea of the syntax.
	Lines longer than 100 characters aren't allowed. This
	should be enough in nearly any case. Mixed lines (config and comments)
	are not allowed. So please use

	# define which proxy to use
	proxy = http://127.0.0.1:3128

	instead of

	proxy = http://127.0.0.1:3128  # define which proxy to use
	

Performance:
-------------

    There is a performance decrease. That couldn't be avoided using the
    redirector system. You can probably increase the speed by allowing
    more squidclam instances. But this will produce higher load for your
    proxy system.

    The access to the www now is working the following way.

    browser    -> squid
    squid      -> squidclam
    squidclam  -> fetch from www and cache in your proxy listening on lo
    squidclam <-> check for virus
    squidclam  -> squid (answer)
    squid      -> serve page to browser which should already be cached because
                  squidclam fetched it just befor

    So there is the time squidclam needs to check the file for a virus
    thats added to the normal time to get a file. Because there are so
    many different files which may contain a virus squidclam scanns every
    file.

    You can increase the performance of your system with the following tweaks.
    
        - use a ramdisk for the temporary files. You REALLY want this!
        - make sure squidclam uses your proxy
        - Make sure squidclam has access to a fast (local) nameserver to
          avoid lookup delays
        - if you have a high load system change the virus db reload
          intervall to something to suite your needs #define RLDB (1000)
        - place the virus db on a ramdisk too
		- squidclam prozesses = 15 + users 


Tempfs: 
--------

new: (since 0.17 default)
   make sure there is a line like the following in you /etc/fstab.
   none /dev/shm tmpfs rw,noexec,nosuid,nodev,size=XXXm  0 0

   
old: (still ok if you use the right config)
    Add the following line to /etc/fstab
    "tmpfs /tmpdata tmpfs rw,noexec,size=XXXm 0 0"

    Make the new Directory
    mkdir /tmpdata

    Mount tmpfs
    imount /tmpdata


Here it is how to create a ramdisk in FreeBSD5.x -6.x. Thanks to Tommaso
    
/sbin/mdconfig -a -t malloc -s 64M -u 10
/sbin/newfs -U /dev/md10
/sbin/mount /dev/md10 /mnt/ramdisk

First line, create a ramdisk called md10, of size 64Mb
Second line, create the filesystem on the device (in this case, UFS)
Third line, mount the device under a specified mountpoint.

For deleting the disk, after unmounting it
/sbin/mdconfig -d -u 10

    
Common Errors:
---------------

E: clamd is not running or not listening for TCP connections
S1: start clamd
S2: netstat -tulpen | grep clamd

E: squid is "misconfigured" and doesn't allow local access
S1: correct this error ;)
S2: try using squidclam on the console by typing something like the following.
    <type>
    ./squidclam <ENTER>
    http://www.eicar.com/download/eicar.com - - GET <ENTER>
    </type>
    Have a look at /var/log/messages
    
E: squidclam isn't working
S1: build squidclam by using the command make debug and see whats going on
    perhaps change ERRIGNORE in squidclam.h to suite your needs.
S2: check the logs!

FAQ:
----

This is the section where I answer the questions of those poor people sitting
behind an ip based blacklist... And of course the questions which are asked very often ;)

--- FAQ 1 ---

> I compiled the squidclam-0.18 package and installed it on a
> SLES 9 x86_64 machine. Compiling and installing was no problem, but
> as I tested the download of the eicar testvirus, I could download the file
> eicar.com without being detected as virus in 3 of 10 cases.
> (used Netscape from Linux and IE from XP)

You probably tried the https files 3 times. Your problem is, squidclam doesn't
get the right URL from squid to download and check the https content. Squidclam
can and will handle https content the right way if you give it the URL as
explained above. So this is sadly not a bug but expected behaviour.  Maybe
there will be a better way to handle https in the future. 

For now you have the following possibilities

- disallow https (bad IMHO)
- allow only trusted https sites (keep an eye on your logs)
- perform a man in the middle attack on the https content

--- FAQ 2 ---

> Will squidclam support unix sockets?

Yes it will.

--- FAQ 3 ---

> Does squidclam allow continuous and non-blocking downloads or does it block
> downloading files until it has successfully scaned them?

as every program that uses the squid redirect_program switch
squidclam first completes the download (action) and after that gives
the url back to squid (which after scanning already has a copy of
the data in its cache).

> Does squidclam scan ftp-data?

if squid is allowed to fetch ftp data squidclam scans it. You can
quickly confirm this doing a ./squidclam
ftp://your.favorit.ftp.server.ru/eicar.test.file.zip - - GET

--- FAQ 4 ---

> To be ...

continued


Sample squid.conf:
-------------------

icp_port 0
#hierarchy_stoplist cgi-bin ?
#acl QUERY urlpath_regex cgi-bin \?
#no_cache deny QUERY
redirect_program /usr/local/bin/squidclam
redirect_children 15
auth_param basic children 5
auth_param basic realm Squid proxy-caching web server
auth_param basic credentialsttl 2 hours
refresh_pattern ^ftp:       1440    20% 10080
refresh_pattern ^gopher:    1440    0%  1440
refresh_pattern .       0   20% 4320
refresh_pattern         \.gif$          10080   100%  43200 override-expire
refresh_pattern         \.jpg$          10080  100%  43200 override-expire
refresh_pattern .               960     90%     43200   reload-into-ims
acl all src 0.0.0.0/0.0.0.0
acl manager proto cache_object
acl localhost src 127.0.0.1/255.255.255.255
acl network  src  192.168.11.0/255.255.255.0
acl to_localhost dst 127.0.0.0/8
acl SSL_ports port 443 563
acl Safe_ports port 80      # http
acl Safe_ports port 21      # ftp
acl Safe_ports port 443 563 # https, snews
acl Safe_ports port 70      # gopher
acl Safe_ports port 210     # wais
acl Safe_ports port 1025-65535  # unregistered ports
acl Safe_ports port 280     # http-mgmt
acl Safe_ports port 488     # gss-http
acl Safe_ports port 591     # filemaker
acl Safe_ports port 777     # multiling http
acl Safe_ports port 901     # SWAT
acl purge method PURGE
acl CONNECT method CONNECT
redirector_access deny SSL_ports
redirector_access deny localhost
http_access allow manager localhost
http_access deny manager
http_access allow purge localhost
http_access deny purge
http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports
http_access allow network
http_access allow localhost
http_access deny all
http_reply_access allow all
icp_access allow all
forwarded_for off
