SQUIDCLAMAV(1)

📦

version 7.5 · 2 versions

7.5 · epel 10, epel 9, fedora 43, fedora 44 (latest)
7.4 · fedora 43, fedora 44

, in epel 10, epel 9, fedora 43, fedora 44

🦋 SQUIDCLAMAV(1) 🦋

okay bestie, welcome to the manual for SquidClamav, part of the User Contributed Perl Documentation crew, living its best life in section 1 of the manual pages. grab a snack, this one's a whole journey ✨

✨ NAME ✨

SquidClamav — HTTP Antivirus for Squid based on ClamAv and the ICAP protocol 🦠🚫

💖 DESCRIPTION 💖

So. SquidClamav is an antivirus for the Squid proxy, and it runs on the ICAP protocol plus the awards-winning ClamAv anti-virus toolkit. Using it? It's gonna help you secure your home network or your enterprise network web traffic. No cap. 💅

It's literally the most efficient antivirus tool for HTTP traffic that's available for free. It's written in C as a c-icap service, and it can handle several thousands of connections at once. Several. Thousands. At once. 👑

Here's the vibe: SquidClamav only scans the HTTP stream that Squid sends through the ICAP server. It does not make HTTP requests itself — which is a gain of performance, and also guarantees that the data being scanned is the exact same data the user requested. iconic behavior, honestly. 🫶

🌸 Why use a c-icap server?

Because it's the only open source icap server written in C, and it's very fast and very stable. that's the whole reason. that's it. 🎀

🌸 Why write yet another clamav c-icap module?

Okay so, being fully honest here — outside of keeping SquidClamav alive and surviving, the author thinks that using clamd instead of libclamav to scan files is speediest and more simple than the srv_clamav module that ships with the c-icap server. simpler, faster, cuter. 🦋

SquidClamav is faster than any other HTTP antivirus and can handle several thousands of simultaneous users at once — and that's exactly what we need. periodt. 🔥

👑 The other unique feature: clamd failover

The other unique feature of SquidClamav is that you can have Clamd failover by setting up up to 4 clamd server IP addresses. When a clamd server is not reachable in one second, SquidClamav switches to the next IP address. automatic glow-up, no drama. ✨

🌈 Google Safe Browsing support

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

Safebrowsing.<something> FOUND

This will be redirected by squidclamav just like if a virus was found. same energy, same drama, same block. 💀🚫

🌸 USAGE 🌸

💫 Generic Program Information 💫

SquidClamav is compatible with all Squid v3.x versions that support the ICAP feature allowing "on stream" scanning. squidclamav is built as a c-icap server service and can be controlled through a configuration file. bestie it's literally plug and play (well, plug and configure) 💅

🌈 Installing Squid 🌈

okay so this heading is just vibes, the actual tea is right below 🫖

👑 Setting SquidClamav as Squid Icap service 👑

I want SquidClamav to be installed as a c-icap service, to be configured as easy as possible and to be compatible with the old configuration file. This means that I voluntary omit some capabilities of c-icap server to preserve a full compatibility with the old squidclamav.conf file. iconic behaviour tbh, backwards compat is the moment ✨

🦋 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 like this 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 enabled you must reinstall Squid with this configuration option or install the additional packages. no skipping this step bestie 😭

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.4.x configuration ⭐

There are some configuration differences between 3.1.x and 3.4.x Squid version. Here are the directives I use for Squid 3.4.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_avi_req reqmod_precache icap://localhost:1344/squidclamav bypass=off
adaptation_access service_avi_req allow all
icap_service service_avi_resp respmod_precache icap://localhost:1344/squidclamav bypass=on
adaptation_access service_avi_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. copy paste and go, we love to see it 🫶

🎀 Squid 3.1.x configuration 🎀

There are some configuration differences between 3.1.x and 3.0.x Squid version. Here are the directives 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 means that in case of squidclamav problems squid will simply ignore the error and continue. lowkey a lifesaver fr fr 💖

💜 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 four configuration lines 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 means that in case of squidclamav problems squid will simply ignore the error and continue.

🌈 What do that configuration directives do? 🌈

They enable Squid's ICAP client and tell Squid to send the logged username and client's IP address to the ICAP server. They also enable preview for faster SquidClamav work. The last four lines define how to call the ICAP server. Here we call the squidclamav service on localhost and port 1344 (host and port can be changed). The bypass parameter set to 1 means that Squid will continue without bothering about ICAP server or SquidClamav failure. This is just like the old bridge mode in previous releases of SquidClamAV. I don't want users to be bored by a continuously error message if SquidClamav or c-icap produce errors or if there's an error in the 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 in case of a failure. your call, bestie, both are valid 💅

🦋 Chained Url Checker 🦋

You can chained SquidClamav call to an Url checked like squidguard by setting the 'url_rewrite_program' squid.conf directive:

url_rewrite_program /usr/bin/squidGuard
url_rewrite_children 15
url_rewrite_access allow all

Call of squidguard from SquidClamav is no longer supported. 💀 rip to a real one

🎀 C-icap server installation/configuration 🎀

If you don't have package solutions or encounter problems when installing SquidClamav I recommend you to install the c-icap server from source as following. You can download it from SourceForge at http://c-icap.sourceforge.net/. Choose version c-icap-0.3.2 or 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 break anything. SquidClamav doesn't use them but reads its own directives from the file /etc/squidclamav.conf. so if you see them, breathe, it's fine 🌸

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

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

This will preserve some resources. efficiency queen behaviour ✨

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 recommend 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 get 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 explained below. 🫶

💖 SquidClamav installation/configuration 💖

Installing SquidClamav requires that you already have installed the c-icap as explained above. You must provide the installation path of c-icap to the configure command as following:

./configure
make
make install

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

Note that if the c-icap installation does not save the c-icap-config program in a directory that can be found in your default path you will need to give the path to this program to squidclamav at configure time:

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

👑 Running 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 into 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. so basically: don't fork, talk to me, and tell me EVERYTHING 😭🔥

🦋 Reloading configuration without restarting the c-icap server 🦋

To force SquidClamav to reread its configuration file after changes 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 its configuration directives and restart pipes to squidGuard. So if you make changes to squidGuard you must execute this command to activate them in SquidClamav.

Or to be sure that everything is really initialized or that you have made change to the c-icap 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 stopping and restarting the c-icap server. The service will just be reinitialized. no downtime, no drama, we love that for us 💅✨

🌈 CONFIGURATION 🌈

By default, the configuration file must be /etc/squidclamav.conf, you may not use another path unless you change it in the source code (see src/squidclamav.h). hardcoded bestie, that's just how it is

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

The format of the configuration file consists in always lower case configuration directive names followed by a value. The name and the value must be separated by a single space character. Comments are lines starting with a '#' character. ngl the format is giving "chill and simple" and we're obsessed 🫶

💫 Global configuration 💫

🎀 Log file and debug 🎀

Logging and debug are handled by the c-icap server. You can control them using the following c-icap.conf directives:

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

So real talk about debug info: it's off by default, and please please please do not turn it on on production systems — it eats performance like it's at an all-you-can-eat buffet 😭. The debug level can go from 1 up to 3 for SquidClamav, but for c-icap it can go all the way up to 10. And if you set

DebugLevel 3

you'll be tracing literally everything SquidClamav does ✨ — which is exactly what you want when you're debugging. Main character detective energy 🔍💅

🦋 Clamd daemon 🦋

SquidClamav needs to know where to hit up clamd, the ClamAV daemon, for that on-stream virus scanning. That's the whole vibe.

clamd_local /tmp/clamd
#clamd_ip 192.168.1.5
#clamd_port 3310

By default SquidClamav contacts clamd locally on the /tmp/clamd unix socket, aka clamd_local. But if your clamd daemon is using an INET socket, or is living its best life on a remote server, then you've gotta set the IP address and the port with clamd_ip and clamd_port. 👑

Heads up bestie: if you're using an INET socket, the clamd_local directive must be commented out, otherwise SquidClamav will always use the clamd_local directive. No exceptions, no cap. 💀

🌈 Clamd failover 🌈

Got multiple ClamAV servers? Obsessed. SquidClamav can do failover between them and honestly it's giving resilience. You just set clamd_ip to a list of IP addresses separated by commas. Do not put space characters in this list or it will break all of it. 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 servers, bestie. And the clamd port must be the same for all of them, because clamd_port only accepts one single value. One. That's it. Periodt. 💅

SquidClamav will always connect to the first IP address available. If that fails, it tries the next defined IP address after 1 second. And once a connect can be established, SquidClamav reuses that last "working" IP address first, so it doesn't slow down the process next time. Efficiency queen 👑

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

timeout 2

Value must be set in seconds. And do not set it too high (< 5) or you can slow down everything. We are not doing that to ourselves. 🙈

🎀 Redirection 🎀

💖 URL redirect 💖

When a virus is detected, SquidClamav needs to redirect the client to a warning page. The SquidClamav distribution contains a whole set of Perl CGI scripts in different languages that you can use 🌍✨. To specify this redirection you have to specify a redirect URL to the redirect directive, as follows:

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

Take a look in the cgi-bin directory to see all translations of this cgi script. So many languages, so iconic. 🫶

SquidClamav will pass the following parameters to this CGI:

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

If this directive is disabled, squidclamav will use c-icap error templates to report issues. See below. 👇

🌸 Using c-icap template instead of redirect scripts 🌸

If the redirect directive is not set, SquidClamav will attempt to load a template up from disk and send this back to the user. By default this template is found at the following path:

/usr/share/c_icap/templates/squidclamav/en/MALWARE_FOUND

Available format tokens are all of those available to the LogFormat directive of c-icap, plus one extra additional token:

%mn — formatted name of the malware, as given by ClamAV. 🦠

🦋 Notice redirection into log file 🦋

To log every redirection, enable the logredir configuration directive:

logredir 1

By default it is disabled, since you can also log this information with the cgi-script or send an email. Options, options, options. 💅

👑 Maximun file size scanned 👑

The maxsize directive allows one to disable virus scan completely for files bigger than the value in bytes. Default is 0, meaning no size limit — as you may want to control download size into squid.conf or clamd instead.

maxsize 2M

If you want to abort virus scan after a certain amount of data, you must take a look at the clamd configuration directive StreamMaxLength, which will close a stream when the given size is reached. That one's clamd's job, not ours, iykyk. ✨

💜 DNS lookup of client IP address 💜

The directive dnslookup allows you to enable / disable DNS lookup of all client IP addresses. Default is enabled:

dnslookup 1

...to preserve backward compatibility. You should deactivate 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. Faster = better, obviously. 🚀

🍓 Multipart content 🍓

Clamd supports decoding email style multipart content and scanning each part. Unless clamd receives a Content-Type header, it can't know how to break up the multipart content, so it tries to scan the entire body as one file — even if parts are base64 encoded. 😭

Enabling the multipart directive:

multipart 0

will force detection of multipart content and send a To: and Content-Type header to clamd before the rest of the body. Disabled by default for backward compatibility. Classic. 🤷

🌈 Safebrowsing 🌈

ClamAV 0.95 introduced support for the Google Safe Browsing database. The database is packed inside a CVD file and distributed through the ClamAV mirror network as safebrowsing.cvd. This feature is disabled by default on all clamav installations. Rude, but okay.

In order to enable this feature, you must first 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. That's the whole ritual 🕯️

Then, to enable this feature into SquidClamav, you have to enable the following configuration directive.

safebrowsing — Enable / Disable Clamav Safe Browsing feature. You must have enabled the corresponding behavior in clamd by enabling SafeBrowsing into freshclam.conf. Enabling it will first make a safe browsing request to clamd and then the virus scan request. 🔥

🎀 URL rejection 🎀

SquidClamav allows you to reject certain URLs based on a regular expression. Rejection is a vibe. 💅

In order to enable this feature, you must first add "reject_url pattern" to freshclam.conf.

reject_url — Allow to specify a regular expression used to reject any matching URL. For example:

reject_url ^[^\?#]+\.(ade|adp|app|asd|asf|asx|bas|bat|cab|chm|cmd|com|cpl|crt|dll|exe|fxp|hlp|hta|hto|inf|ini|ins|isp|jse?|lib|lnk|mdb|mde|msc|msi|msp|mst|ocx|pcd|pif|prg|reg|scr|sct|sh|shb|shs|sys|url|vb|vbe|vbs|vcs|vxd|wmd|wms|wmz|wsc|wsf|wsh)([\?#].*)?$

⭐ Control virus scan ⭐

There are two scan modes to fully control squidclamav behavior. The first and historical mode is "ScanAllExcept", which scans everything by default. This mode can be controlled by the directives: abort, abortcontent, whitelist, trustuser and trustclient.

scan_mode ScanAllExcept

The second mode, since squidclamav version 7, is "ScanNothingExcept", which will scan nothing but the content controlled by scan, scancontent, blacklist, untrustuser and untrusted client.

scan_mode ScanNothingExcept

Any other value for the scan_mode directive will force the "ScanAllExcept" mode. This guarantees backward compatibility with older squidclamav versions. Nostalgia arc 🫶

💖 abort 💖

The abort directive will let you disable virus scanning at URL level (not chained program). When the URL matches the regex pattern, SquidClamav falls back to Squid immediately after the call to the chained program, if one is defined there.

For example:

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

The first regexp will exclude any file hosted on domain squid-cache.org from virus scanning, and the last one will exclude all PNG, GIF and JPEG images from scanning. Images stay winning 🖼️✨

Only used in "ScanAllExcept" mode.

🌸 abortcontent 🌸

The abortcontent directive allows you to exclude any file from virus scanning whose Content-Type matches the regex pattern. This directive costs more time because SquidClamav needs to download the HTTP header for a file with a HEAD request. Note that some sites do not answer to HEAD requests, so the content type will not be able to be retrieved — so they will be scanned. Sneaky little sites. 🙈

Example:

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

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

Only used in "ScanAllExcept" mode.

🦋 whitelist 🦋

The whitelist configuration directive allows you to disable chained program and virus scan at URL level. When the given pattern matches the URL, SquidClamav falls back to Squid instantly.

For example:

whitelist \.clamav\.net

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

You can also use a file containing all regexes that might be whitelisted and provide the file name to the whitelist directive. Suppose that you have a file named /usr/local/c-icap/etc/sc_whitelist with the following content:

\.clamav\.net
\.darold\.net

then you just have to set whitelist in squidclamav.conf as follows:

whitelist /usr/local/c-icap/etc/sc_whitelist

The file must contain only one regex per line and no extra character. Clean lines only, bestie. 🧼

Only used in "ScanAllExcept" mode.

👑 trustuser 👑

The trustuser directive allows you to disable chained program and virus scan when an ident matches the search pattern. On regex found, SquidClamav falls back to Squid instantly. Of course you must have the Squid authentication helper enabled.

For example:

trustuser administrator

will let the user logged in as administrator not be bored by the chained program and virus scan. Protected. Privileged. Iconic. 💅

Only used in "ScanAllExcept" mode.

💜 trustclient 💜

The trustclient directive allows you to disable chained program and virus scan if the client source IP address or DNS name matches the search pattern. The source IP address can be a single IP address or an address range 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 it for an entire class C network. Whole network eating good. 🌐

Only used in "ScanAllExcept" mode.

⭐ scan ⭐

The scan directive will let you enable virus scanning at URL level.

For example:

scan .*\.(doc|docx|pdf|xls)$

The regexp is going to force virus scanning for the extensions .doc, .docx, .pdf and .xls. 💖

Heads up bestie: this one is only used in "ScanNothingExcept" mode. 👑

✨ scancontent ✨

The scancontent directive lets you force virus scanning for certain files whose Content-Type matches the regex pattern you give it. 🌸

Fair warning though — this one is lowkey expensive, because SquidClamav has to download the HTTP header for a file with a HEAD request. And some sites literally do not answer HEAD requests at all, which means the content type can't be retrieved… and in that case, they get scanned anyway. No cap. 💅

Example:

scancontent ^application\/.*$

Only used in "ScanNothingExcept" mode. 👑

✨ blacklist ✨

The blacklist configuration directive is your "force virus scan at URL level" button. 🎀

For example:

whitelist \.badsite\.com

will force scanning any files from hosts on the badsite.com domain. (Yes, that's exactly what the original says — I'm just the messenger bestie 😭)

You can also use a file containing all the regexes that might be blacklisted and hand that file name to the blacklist directive. Say you have a file named /usr/local/c-icap/etc/sc_blacklist with this content:

\.badsite\.com
\.getyourvirus\.org

then you just have to set blacklist in squidclamav.conf like this:

blacklist /usr/local/c-icap/etc/sc_blacklist

That file must contain only one regex per line and no extra character. Periodt. ✨

Only used in "ScanNothingExcept" mode. 👑

✨ untrustuser ✨

The untrustuser directive forces a virus scan when an ident matches the search pattern. And of course, you must have the Squid authentication helper enabled for this to even be a thing. 🦋

For example:

untrustuser fakeuser

Only used in "ScanNothingExcept" mode. 👑

✨ untrustclient ✨

The untrustclient directive forces a virus scan if the client source IP address or DNS name matches the search pattern. The source IP can be a single IP address, or an address range following the given regex pattern. 🌈

For example:

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

The first and the last entry will force a virus scan for a single computer, and the second one does it for an entire class C network. Main character energy fr. 💅

Only used in "ScanNothingExcept" mode. 👑

🗜️ Libarchive support 🗜️

This lets squidclamav uncompress archives and filter according to user-defined rules before passing them along to clamav. Check the directives below for the details. 🫶

enable_libarchive

Enable/disable use of libarchive by SquidClamav. Disabled by default. 🚫

Note: if libarchive is not available on your server, enabling this feature will have no effect. When libarchive headers are not present, the code to support libarchive in squidclamav is simply not compiled. 💀

ban_archive_entry

Block matching archive entries. For example: zip files containing threats such as ransomware that are not yet detected by clamav or other antivirus software (typically 5KB zip files containing a cab file or a vbe script). 🦠

Here is the value set in the configuration file if enabled:

ban_archive_entry ^.*\.(ade|adp|app|asd|asf|asx|bas|bat|cab|chm|cmd|com|cpl|crt|dll|exe|fxp|hlp|hta|hto|inf|ini|ins|isp|jse?|lib|lnk|mdb|mde|msc|msi|msp|mst|ocx|pcd|pif|prg|reg|scr|sct|sh|shb|shs|sys|url|vb|vbe|vbs|vcs|vxd|wmd|wms|wmz|wsc|wsf|wsh)$

ban_max_entries

Maximum number of entries in an archive in order to block it, if there's at least one match. Archives with more than ban_max_entries will not be blocked, even if there are matches. 😭

A value of 0 (or commented out) will ignore the number of entries in an archive.

Suggested value: 1.

ban_max_matched_entries

Maximum number of matched entries in an archive in order to block it. Archives with more than ban_max_matched_entries matches will not be blocked. 🙈

A value of 0 (or commented out) will ban an archive when there's at least one entry match.

Suggested value: 1.

banmaxsize

Maximum size of an archive that may be opened. Any file bigger than this value will not be scanned. 🔥

Suggested value: 2M.

recoverpath

Path where banned archives are stored (libarchive). Hard-coded file format:

banned_USERNAME_CLIENTIP_UNIXTIME_RAND(99).FILEEXTENSION

USERNAME and CLIENTIP are available when enabling icap_send_client_ip and icap_send_client_username in squid.conf. Check the clwarn.cgi example to see how you can retrieve the file name and serve it via http. 💅

recovervirus

Enable if virus files should also be copied to recoverpath. Hard-coded file format:

virus_USERNAME_CLIENTIP_UNIXTIME_RAND(99).FILEEXTENSION

Otherwise, only archives containing ban_archive_entry matches will be copied. ✨

🧪 Testing SquidClamav 🧪

As SquidClamav is a c-icap service, it can not be run at console as an interactive program. Sorry bestie, no REPL for you. 🙈

To check what is going wrong, you must edit the c-icap.conf file, set DebugLevel to 3 and enable ServerLog. Then check for lines with the squidclamav string in the log file, which is defined with ServerLog in squidclamav's config. 🦋

🚀 Performance 🚀

With SquidClamav, the way to tune your service is to tune the c-icap server and the clamd daemon. On heavy http access, putting the clamd daemon on a dedicated server with multiple CPU will really help. 🔥

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

🌸 FAQ 🌸

FTP uploads (STOR/put) hang with Squid's native FTP proxy (ftp_port)

When Squid is used as a native FTP proxy ("ftp_port"), directory listings and downloads work — but uploads (FTP STOR) hang and time out on the client as soon as REQMOD adaptation is enabled. Commenting out the ICAP/adaptation directives makes uploads work again. 😭

This is not a SquidClamav bug. Squid's native FTP relay does not forward the uploaded file as an HTTP request body: it presents every FTP command to the REQMOD service as a body-less "GET ftp://host/" request. SquidClamav therefore correctly answers "204 No modification" (there is nothing to scan), and Squid then deadlocks while coordinating the FTP data channel with the REQMOD transaction. The upload bytes never reach SquidClamav. 💀

The same hang has been reported with a plain pass-through ICAP service, which confirms the problem originates in Squid, not in the adaptation service.

Workaround: skip REQMOD for the FTP protocol while keeping RESPMOD, so FTP downloads are still scanned:

acl ftp_proto proto FTP
adaptation_access service_req deny ftp_proto
adaptation_access service_req allow all
adaptation_access service_resp allow all

With this configuration:

HTTP uploads (POST/PUT) : scanned (REQMOD) - unaffected
FTP downloads (RETR)    : scanned (RESPMOD)
FTP uploads (STOR)      : not scanned, but no longer hang

Scanning native-FTP uploads requires a fix in Squid's FTP relay so that the STOR body is forwarded to REQMOD; there is nothing SquidClamav can do from the ICAP side until then. 🤷

🐛 BUGS 🐛

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

💡 FEATURE REQUESTS 💡

If you need new features, let me know at <gilles AT darold DOT net>. This helps 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 requests or patches and they 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 software. 🌈

Special thanks to Christos Tsantilas for his implementation of the c-icap server. Lots of SquidClamav source code has been learned or simply cut and pasted from the source code of his clamav service. 🫡

I must also thank all the great contributors and all others who help to build a useful and reliable product. They are all cited in the ChangeLog file. 💜

⚖️ LICENSE ⚖️

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

And that's the whole page bestie, we made it to the end 🎀 this one was rendered by perl v5.38.2, dated 2026-06-28, and it's officially the SQUIDCLAMAV(1) manual page. Slay, go scan some files responsibly. 💅✨🦋

📦 where this page comes from

epel 10: squidclamav 7.5-1.el10_3 · GPL-3.0-or-later
epel 9: squidclamav 7.5-1.el9 · GPL-3.0-or-later
fedora 43: squidclamav 7.5-1.fc43 · GPL-3.0-or-later
fedora 44: squidclamav 7.5-1.fc44 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms