NAME
    SquidClamav v6 - HTTP Antivirus for Squid based on ClamAv and the ICAP
    protocol

DESCRIPTION
    SquidClamav v6 is an antivirus for the Squid proxy based on the ICAP
    protocol and the Awards winnings ClamAv anti-virus toolkit. Using it
    will help you securing your home or enterprise network web traffic.
    SquidClamav is the most efficient antivirus tool for HTTP traffic
    available for free, it is written in C as a c-icap service and can
    handle several thousands of connections.

    Previous versions was only working as Squid Redirector but this had some
    bad limitations and breaks many sites using cookies and post HTTP
    method. The reason is that older squidclamav release (< 6.0) had to
    request through libcurl the URL given by Squid to download the file and
    scan it. But this URL doesn't include the post parameters nor any header
    information like cookies. The other advantage is that you can now scan
    video/audio streaming without problem.

    SquidClamav v6 bypass theses limitations by only scanning the HTTP
    stream sent by Squid through the ICAP server. It don't make HTTP request
    itself so this is a gain of performance and ensure that the data scanned
    are the same that the user has requested.

    Why use c-icap server? This is the only open source icap server written
    in C, that mean it is very fast and as I know/tested stable enough. I
    don't have time to write my own so I think this is the best choice. If
    you don't think so and reports me too many problems related to c-icap
    don't worry I will help to make it better otherwise I will write my own
    but the best choice is to help c-icap.

    Why writing and other clamav c-icap module? Well, to be honest, outside
    the survival of SquidClamav, I think that using clamd instead of
    libclamav to scan files is speediest and more simple than the srv_clamav
    module provided with the c-icap server. The other argument is that you
    can have your own redirect page like with previous version of
    SquidClamav. And to ending this part SquidGuard can still be call and
    used like in previous release, It means faster and with dedicated
    redirect page defined in your squidGuard configuration file.

    SquidClamav v6 is still faster than any others and can handle several
    thousands of simultaneous users, this is what we need.

    The other unique feature of SquidClamav is that you can have Clamd
    failover by setting up to 4 clamd server ip address. When a clamd server
    is not reachable in the second, SquidClamav switch the next ip address.

    If you are using ClamAV above 0.95, SquidClamav will have support for
    Google Safe Browsing database. All signatures provided by Google Safe
    Browsing Database will be prefixed with the Safebrowsing tag. If ClamAV
    reports:

            Safebrowsing.<something> FOUND

    this will be redirected by squidclamav just like if a virus was found.

USAGE
  Generic Program Information
    SquidClamav v6 has been completely rewritten to be use through the Squid
    v3.x ICAP feature allowing "on stream" scanning. It is now built as a
    c-icap server service but keeps all features from v5 and is fully
    compatible with the old SquidClamav configuration file. The squidclamav
    configuration file is unchanged minus some obsoletes directives.

    This also mean that SquidClamav can no more be run into an interactive
    console for testing your URL. All debug information will now goes to the
    c-icap logfile.

  Installing Squid
  Setting SquidClamav as Squid Icap service
    I want SquidClamav as c-icap service to be installed and configured the
    more easier as possible and compatible with the old configuration file.
    This mean that I voluntary omit some capabilities of c-icap server to
    preserve a full compatibility with the old squidclamav.conf file.

   Squid v3.x installation and configuration
    To have full and stable icap support with Squid you must use the 3.x
    branch and configure squid with the following option:

            --enable-icap-client

    I don't know what other options you are using but you have to add this
    one to your configure command. If you prefer to use distribution
    packaging you may already have it configured if you can install the
    c-icap package too.

    If you don't know, run the following command an search for the
    configuration directive: --enable-icap-client

            /usr/local/squid/sbin/squid -v | grep "enable-icap-client"

    If it is not enable you must reinstall Squid with this configuration
    option or install the additional packages.

    Once you have it enabled, to integrate c-icap and SquidClamav to your
    squid cache just edit squid.conf and set the following directives.

    Squid 3.1.x configuration
        There's some configuration difference between 3.1.x and 3.0.x Squid
        version. Here are those I use for Squid 3.1.x:

                icap_enable on
                icap_send_client_ip on
                icap_send_client_username on
                icap_client_username_encode off
                icap_client_username_header X-Authenticated-User
                icap_preview_enable on
                icap_preview_size 1024
                icap_service service_req reqmod_precache bypass=1 icap://127.0.0.1:1344/squidclamav
                adaptation_access service_req allow all
                icap_service service_resp respmod_precache bypass=1 icap://127.0.0.1:1344/squidclamav
                adaptation_access service_resp allow all

        If you don't know where to put them in squid.conf, just search for
        'icap_.*' and add those configuration lines at the end of the icap
        section.

        Here the bypass is set to 1, that mean that in case of ICAP problem
        squid will simply ignore the error and continue. This is the
        equivalent of the bridge mode in version 5.x. I recommand to disable
        this feature when you want to check the load on your server to be
        able to tune c-icap and clamd.

    Squid 3.0.x configuration
        For squid 3.0.x you must replace 'bypass=1' by '1' or 'bypass=0' by
        '0' and the access to the service is defined at a class level. Only
        the last fourth configuration line change from version 3.1.x.

                icap_enable on
                icap_send_client_ip on
                icap_send_client_username on
                icap_client_username_encode off
                icap_client_username_header X-Authenticated-User
                icap_preview_enable on
                icap_preview_size 1024
                icap_service service_req reqmod_precache 1 icap://127.0.0.1:1344/squidclamav
                icap_service service_resp respmod_precache 1 icap://127.0.0.1:1344/squidclamav
                icap_class class_avreq service_req
                icap_class class_avresp service_resp
                icap_access class_avreq allow all
                icap_access class_avresp allow all

        If you don't know where to put them in squid.conf, just search for
        'icap_.*' and add those configuration lines at the end of the icap
        section.

        Here the bypass is set to 1, that mean that in case of ICAP problem
        squid will simply ignore the error and continue. This is the
        equivalent of the bridge mode in version 5.x. I recommand to disable
        this feature when you want to check the load on your server to be
        able to tune c-icap and clamd.

    What that configuration directives do? It enables the ICAP client into
    Squid and tells Squid to send the logged username and client's Ip to the
    ICAP server. It also enable preview for faster SquidClamav work. The
    last four lines defined how to call the ICAP server. Here we call the
    squidclamav service on localhost and port 1344 but it can be on any
    other host and port. The bypass parameter set to 1 mean that Squid will
    continue without bothering about ICAP server or SquidClamav failure.
    This is just like the old bridge mode in the SquidClamav previous
    release. I don't want users to be bored by a continuously error message
    if SquidClamav or c-icap have failure or if there's an error in
    configuration file. Users don't have to know about that, they want to
    surf and don't care about your problems :-) If you don't think like me,
    just set the bypass argument to 0 and Squid will return an error message
    on failure.

   C-icap server installation/configuration
    If you don't have package solution or encounter problem to install
    SquidClamav I recommand you to install the c-icap server from source as
    follow. You can download it from SourceForge at
    http://c-icap.sourceforge.net/. Choose version c-icap-0.1.2 and later
    versions, then run:

            ./configure --prefix=/usr/local/c-icap --enable-large-files
            make
            make install

    Then, edit the file /usr/local/c-icap/etc/c-icap.conf. It contains a set
    of documented values that configure the c-icap server. To enable the
    support of SquidClamav just add the following line to the end of the
    file:

            Service squidclamav squidclamav.so

    Don't care about the srv_clamav.* configuration directives this will not
    breaks anything. SquidClamav do not use them but read its own directives
    from the file /etc/squidclamav.conf

    You can disable the c-icap embedded modules by commenting the lines:

            #Service url_check_module srv_url_check.so
            #Service antivirus_module srv_clamav.so

    this will preserve some resources.

    Following your installation you may need to create the /var/run/c-icap/
    where c-icap server is writing pid and socket file.

    You may also want to change the user/group owning c-icap's processes. By
    default the owner is the user/group who runs the program. I recommand
    you to change them to the same user/group running your Squid cache. For
    example:

            User proxy
            Group proxy

    of course you will need to change the owner of directory
    /var/run/c-icap/ and the directory of your server log. See the ServerLog
    directive to know the path. For me, I use the following commands to set
    the good rights on my installation:

            mkdir /var/run/c-icap/
            chown -R proxy:proxy /var/run/c-icap/
            chown -R proxy:proxy /usr/local/c-icap/

    After that you can run the c-icap server as explain below.

   SquidClamav installation/configuration
    Installing SquidClamav require that you already have installed the
    c-icap as explain above. You must provide the installation path of
    c-icap to the configure command as follow:

            ./configure --with-c-icap=/usr/local/c-icap/
            make
            make install

    this will install the squidclamav.so library into the c-icap
    modules/services repository.

   Runing c-icap server
    Finally, you can run the c-icap server as root user:

            /usr/local/c-icap/bin/c-icap

    Or any other path to the binary. If you want to display debugging
    information on the terminal, the previous command should be executed
    with the following arguments:

            /usr/local/c-icap/bin/c-icap -N -D -d 10

    The first argument -N prevents the c-icap server from forking in the
    background, the second argument -D enables the printing of messages to
    standard output, and the third argument -d 10 enables the printing of
    full debugging information.

   Reloading configuration without restarting the c-icap server
    To force SquidClamav to reread his configuration file after change you
    can send the following command to the c-icap server

            echo -n "squidclamav:cfgreload" > /var/run/c-icap/c-icap.ctl

    It will reread all his configuration directive and restart pipes to
    squidGuard. So if you make changes to squidGuard you must execute this
    command to activate them into SquidClamav.

    Or to be sure that all is really initialized or that you have made
    change to the c-icapi configuration file you can run the following
    command:

            echo -n "reconfigure" > /var/run/c-icap/c-icap.ctl

    The service will reread the config file without the need for stop and
    restart the c-icap server. The services will be reinitialized.

CONFIGURATION
    By default, the configuration file must be /etc/squidclamav.conf, you
    can not use an other path unless you change it in the source code (see
    src/squidclamav.h).

    SquidClamav installation will create a default file with the maximum
    security level. If you have low resource on your server there's some
    predefined pattern optimized for speed. Feel free to modify it to match
    your security level.

    The format of the configuration file consists in always lower case
    configuration directives name followed by a value. The name and the
    value must be separated by a single space character. Comments are lines
    starting with a '#' character.

  Global configuration
   Log file and debug
    In version 6.x the directives 'logfile', 'debug' and 'stat' are
    obsoletes as logging and debug are now handle by the c-icap server. You
    can control them using the c-icap.conf directives:

            ServerLog /usr/local/c-icap/var/log/server.log
            DebugLevel 0

    Debug informations are disable by default, do not enable it on
    production server as it cost a lot of system performance. The debug
    level can be set from 1 up to 3 for SquidClamav but can be up to 10 for
    c-icap.

   Clamd daemon
    SquidClamav need to know where to contact clamd, the ClamAv daemon, for
    on stream virus scanning.

            clamd_local /tmp/clamd
            #clamd_ip 192.168.1.5
            #clamd_port 3310

    By default SquidClamav will contact clamd locally on the /tmp/clamd unix
    socket (clamd_local). If your clamd daemon use INET socket or stay in a
    remote server, you have to set the ip address and the port with clamd_ip
    and clamd_port.

    If you use INET socket the 'clamd_local' directive must be commented
    else SquidClamav will always used the clamd_local directive.

   Clamd failover
    If you have multiple ClamAv servers, SquidClamav is able to do failover
    between them. You just have to set 'clamd_ip' to a list of ip adresses
    separated by a coma. Do not insert space character in this list it will
    break all. For example:

            clamd_ip 192.168.1.5,192.168.1.13,192.168.1.9
            clamd_port 3310
            timeout 1

    You can set up to 5 clamd server. The clamd port must be the same for
    all these server as 'clamd_port' only accept one value.

    SquidClamav will always connect to the first available ip address. If it
    can not connect after 1 second it will try the next defined ip address.
    When a connect can be establish SquidClamav will reuse this last
    "working" ip address first to not slow down process the next time.

    If you think 1 second is a low value, you can change the connect timeout
    by editing file squidclamav.conf and set the 'timeout' directive to a
    higher value.For example :

            timeout 2

    Value must be set in second. Do not set it too high (< 5) or you can
    slow down everything.

   Redirection
    When a virus is detected SquidClamav need to redirect the client to a
    warning page. You can find in the SquidClamav distribution a set of Perl
    CGI scripts with different language that you can use. To specify this
    redirection you have to use the 'redirect' directive as follow:

            redirect http://proxy.samse.fr/cgi-bin/clwarn.cgi

    Take a look in the cgi-bin directory to see all translation of this cgi
    script.

    Squidclamav will pass to this CGI the following parameters:

            url=ORIGNAL_HTTP_REQUEST
            virus=NAME_OF_THE_VIRUS
            source=DOWNLOADER_IP_ADDRESS
            user=DOWNLOADER_IDENT

    To log every chained program redirection enable the 'logredir'
    configuration directive as follow:

            logredir 1

    By default it is disabled as you can also log this information with the
    cgi-script or send an email.

   Chained Url Checker
    SquidClamav allow you to chain the SquidGuard program to check the Url
    requested against blocklists using the 'squidguard' directive. You just
    have to give the path to the program.

            squidguard /usr/local/squidGuard/bin/squidGuard

    The chained program is called before the virus scan and any other
    SquidClamav operation. The call to this program can be disable with the
    'whitelist', 'trustuser' and 'trustclient' directives see SquidClamav
    Patterns for more information.

    To log every chained program redirection enable the 'logredir'
    configuration directive as follow:

            logredir 1

    By default it is disabled as you can also log this information with
    squidguard.

   Maxsize
    This directive allow to completely disable virus scan for files bigger
    than the value in bytes. Default is 0, no size limit as you may want to
    control download size into squid.conf or clamd.

            maxsize 2000000

    If you want to abort virus scan after a certain amount of data you must
    take a look at the clamd configuration directive 'StreamMaxLength' that
    will close stream when the given size is reach.

  Controlling SquidClamav behaviour
    As in SquidClamav v5.x, v6.0 will scan all downloaded files by default.
    You have five directives to control the way things must work.

    All these directives used extended regex pattern matching and are case
    insensitive.

   Control both chained program and virus scan
    There's 3 configuration directives that allow you to disable virus scan
    and call to chained redirector like SquidGuard. Those pattern matching
    are searched as soon as a Squid entry is received.

    whitelist
        The 'whitelist' configuration directive allow you to disable chained
        program and virus scan at URL level. When the given pattern match
        the URL SquidClamav fallback to Squid instantly.

        For example:

                whitelist \.clamav\.net

        will deliver any files from hosts on clamav.net domain directly.

    trustuser
        The 'trustuser' directive allow you to disable chained program and
        virus scan when an ident match the search pattern. On regex found
        SquidClamav fallback to Squid instantly. Of course you must have
        Squid authentication helper enabled.

        For example:

                trustuser administrator

        will let user logged as administrator to not be bored by chained
        program and virus scan.

    trustclient
        The 'trustclient' directive allow you to disable chained program and
        virus scan if the client source ip address or DNS name match the
        search pattern. The source ip address can be a single ip or a
        network following the given regex pattern.

        For example:

                trustclient ^192\.168\.1\.1$
                trustclient ^192\.168\.1\..*$
                trustclient ^mypc\.domain\.dom$

        The first and the last entry will disable chained program and virus
        scan for a single computer and the second will do for en entire
        class C network.

    dnslookup
        Enable / disable DNS lookup of client ip address. Default is enabled
        '1' to preserve backward compatibility but you must desactivate this
        feature if you don't use trustclient with hostname in the regexp or
        if you don't have a DNS on your network. Disabling it will also
        speed up squidclamav.

   Control virus scan
    There's 3 configuration directives that allow you to disable virus scan
    for downloaded files.

    abort
        The 'abort' directive will let you disable virus scanning at URL
        level (not chained program). When the URL match the regex pattern
        SquidClamav fallback to Squid immediately after the call to the
        chained program if there's one defined.

        For example:

                abort \.squid-cache\.org
                abort .*\.(png|gif|jpg)$

        The first regexp will exclude from virus scanning any file hosted on
        domain squid-cache.org, the last one will exclude all PNG, GIF and
        JPEG image from scanning.

    abortcontent
        The 'abortcontent' directive allow you to exclude from virus
        scanning any file whose Content-Type match the regex pattern. This
        directive cost more time because SquidClamav need to download the
        HTTP header for a file with a HEAD request. Note that some sites do
        not answer to HEAD request so content type could not be retrieved so
        they will be scanned.

        Example:

                abortcontent ^image\/.*$
                abortcontent ^video\/x-flv$

        The first directive will complete the "abort .*\.(png|gif|jpg)$"
        previous directive to match dynamic image or with parameters at end.
        The second will allow your users to view streamed video instantly.

    maxsize
        As said above, the 'maxsize' directive allow you to not scan a file
        when the content-length of the file is bigger than the defined
        value. By default there's no size limit.

   Safebrowsing
    ClamAV 0.95 introduced support for Google Safe Browsing database. The
    database is packed inside a CVD file and distributed through our mirror
    network as safebrowsing.cvd . This feature is disabled by default on all
    installations and should be enabled with extreme care.

    All signatures provided by Google Safe Browsing Database will be
    prefixed with the Safebrowsing tag. If ClamAV reports
    Safebrowsing.<something> FOUND, it means that the advisory was provided
    by Google and not by ClamAV Virus database.

    Please note that such reports do NOT necessarily mean that the data
    scanned contains some malware. You should treat such data as a potential
    risk, that is a suspicious source of malware.

    If you want to know more about the potentially dangerous data matched by
    the signature, you should visit http://www.antiphishing.org/ (for
    phishing warnings) or http://www.stopbadware.org/ (for malware
    warnings).

    In order to enable this feature, you must add “SafeBrowsing Yes” to
    freshclam.conf . There is no option in clamd.conf. If the engine finds
    Google Safe Browsing files in the database directory, ClamAV will enable
    safe browsing. To turn it off you need to update freshclam.conf and
    remove the safebrowsing files from the database directory before
    restarting clamd.

  Testing SquidClamav
    As SquidClamav v6.0 is now a c-icap service it can no more be run at
    console in interactive mode. To check what is going wrong you must edit
    c-icap.conf fine and set DebugLevel to 3 and enable ServerLog. Then
    check for line with squidclamav string into the log file defined with
    ServerLog.

  Performances
    With SquidClamav v6.x the way to tune your service is to tune c-icap
    server and clamd daemon. On heavy http acces, putting the clamd daemon
    on a dedicated server with mutilple CPU will really help.

    If you experience Squid "ICAP protocol error" (with bypass enabled)
    please consider increasing the c-icap following parameters:
    StartServers, MaxServers, MinSpareThreads, MaxSpareThreads,
    ThreadsPerChild. Increase also in clamd.conf parameter: MaxThreads may
    help.

BUGS
    Please report any bugs, patches, discussion, etc. to <gilles AT darold
    DOT net>.

FEATURE REQUEST
    If you need new features let me know at <gilles AT darold DOT net>. This
    help a lot to develop a better/useful tool.

HOW TO CONTRIBUTE ?
    Any contribution to build a better tool is welcome, you just have to
    send me your ideas, features request or patches and there will be
    applied.

AUTHOR
    Gilles Darold <gilles AT darold DOT net>

ACKNOWLEDGEMENT
    Thanks to Squid-cache.org, Clamav.net and c-icap.sf.net for their great
    softwares.

    Specials thanks to Christos Tsantilas for his implementation of the
    c-icap server. Lot's of SquidClamav v6 source code have been learn or
    simply cut and paste from the source code of his clamav service.

    I must also thanks all the great contributors:

            - Leonardo Humberto Liporati from www.ig.com.br
            - Dale Laushman from The Uptime Group
            - Rainer schoepf from Proteosys.com

    and all others who help me to build a usefull and reliable product.

LICENSE
    Copyright (c) 2005-2012 Gilles Darold - All rights reserved.

    Some code are Copyright (C) 2004-2008 Christos Tsantilas

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation, either version 3 of the License, or any later
    version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program. If not, see < http://www.gnu.org/licenses/ >.

