Server admin

Set up the virus scanner (ClamAV).

Farwing can send each incoming file to ClamAV before the file is released. This page is how to run ClamAV and connect it.

What it does

Farwing sends each incoming file to ClamAV, a free virus scanner, before the file is released.

Clean files go through.

Infected files go to quarantine.

Choose what to scan, and what to do with a file the scanner cannot decide, on the virus scanning page.

What you need

ClamAV needs 3 GiB of memory at minimum. 4 GiB is better.

It uses about 1.2 GiB to load the virus definitions.

It uses about 2.4 GiB for a short time once a day, when it reloads the definitions.

Allow about 500 MB of disk for the definitions.

The server needs a path to ClamAV’s update servers, or a local copy of the definitions. A server with no internet is covered in Servers with no internet.

The memory figures and the image tags are ClamAV’s. Read them on ClamAV’s Docker page.

Turn it on with Docker Compose

The scanner is in the Compose file, and it is off until you ask for it. This starts the scanner beside the server. A plain start does not start the scanner.

docker compose --profile antivirus up -d

The first start downloads the virus definitions. It takes a few minutes. This follows the scanner log until the scanner is ready.

docker compose logs --follow clamav

The image checks itself. This reads that check, so you can see when the scanner is answering.

docker inspect --format "{{.State.Health.Status}}" clamav

Wait until the check says healthy.

Connect it in Farwing

Open Admin, then Scanning.

The status card says “Virus scanner found. Scanning is ready.” when ClamAV is answering.

Pick ClamAV.

Receive links and packages from outside senders are scanned by default. Leave those on unless you have a reason to change them.

Save. Scanning stays off until you save.

Test it

Upload the EICAR test file through a receive link. EICAR is a harmless file. Every scanner reports it as a virus.

The file lands in quarantine.

The administrator email arrives.

Keeping it up to date

The official image runs freshclam inside the container. By default it checks for new definitions once a day. The schedule is on ClamAV’s Docker page.

This shows the last update in the scanner log.

docker compose logs clamav

Farwing’s Scanning page also shows the definitions date on the status card.

Update the scanner program about once a month, and whenever ClamAV announces a security fix. This downloads the newest image. The definitions volume is kept.

docker compose pull clamav

This restarts only the scanner, on the new image. The server keeps running.

docker compose --profile antivirus up -d clamav

A container update tool can do this for you.

Servers with no internet

A server that cannot reach the internet can use a local copy of the definitions.

ClamAV’s tool for that copy is cvdupdate. Follow ClamAV’s private-mirror page.

Point the scanner’s update setting at your copy, then start the scanner as above.

Without Compose

You can run the same scanner with docker run.

This creates the named volume. The volume keeps the definitions when the container is replaced.

docker volume create clamav-db

This starts the scanner. The port is open on this computer only, so other computers cannot reach it.

docker run --detach --name clamav --restart unless-stopped --publish 127.0.0.1:3310:3310 --mount source=clamav-db,target=/var/lib/clamav clamav/clamav:1.4_base

Then connect it in Farwing, as in Connect it in Farwing.

Use a scanner you already run

Open Admin, then Scanning.

For a ClamAV you already run, pick ClamAV and enter its host and port.

For a company scanner, pick ICAP and enter the service address. ICAP is chosen on the virus scanning page.

Large files

ClamAV skips a file that is over its size limits.

Set StreamMaxLength and MaxFileSize to 4 GB. The largest value ClamAV accepts is 4095M, which is just under 4 GB.

Put StreamMaxLength 4095M and MaxFileSize 4095M in clamd.conf. The other size settings are on the virus scanning page.

ClamAV’s Docker page applies that file by mounting your configuration directory on /etc/clamav. This starts the scanner with that directory. Replace /path/to/clamav with the directory that holds the file.

docker run --detach --name clamav --restart unless-stopped --publish 127.0.0.1:3310:3310 --mount source=clamav-db,target=/var/lib/clamav --mount type=bind,source=/path/to/clamav,target=/etc/clamav clamav/clamav:1.4_base

The image also reads the same settings from environment variables. This starts the scanner with the two limits, without a configuration file.

docker run --detach --name clamav --restart unless-stopped --publish 127.0.0.1:3310:3310 --mount source=clamav-db,target=/var/lib/clamav --env CLAMD_CONF_StreamMaxLength=4095M --env CLAMD_CONF_MaxFileSize=4095M clamav/clamav:1.4_base

A file over the limit follows the setting “The file is too large to scan”. The default is “Hold for an administrator”.

Troubleshooting

The container restarts, or the system kills it

The cause is memory. ClamAV needs 3 GiB, and 4 GiB is better, including the short reload each day.

Give the server more memory, or move the scanner to a computer that has it.

The page says “No virus scanner is connected”

The scanner is not started, the port is not 3310 on this computer, or the first download is still running.

Start it with the antivirus profile, wait until the health check says healthy, then reload the Scanning page.

The definitions are old

The scanner cannot reach the update servers, or the update servers are refusing too many requests.

Check the scanner log for the update error. Use a local copy if this server has no internet.

Scans are slow

The file is near the size limit, or the server’s processor is busy.

Raise the size limits if the file is being skipped, or give the scanner more processor time.