ClamFS

ClamFS - User-space fs with on-access antivirus scanning

Description

ClamFS is a FUSE-based user-space file system for Linux and BSD with on-access anti-virus file scanning through clamd daemon (a file scanning service developed by ClamAV Project).

Features

• Scans files using ClamAV
• User-space file system (no kernel patches, modules, recompilations, etc.)
• Based on libFUSE version 3 (until version 1.1.0 on libFUSE v2)
• Implements all clamd scan modes: fname, fdpass and stream
• Supports remote clamd instances in stream mode over TCP/IP socket
• Caches scan results in a LRU cache with time-based and out-of-memory expiration
• Configuration stored in XML files
• Supports ulockmgr
• Sends mails to administrator when detects virus

Table of contents

• Description
  • Features
• Getting Started
  • Installing packages
    • Arch
    • Debian, Ubuntu, etc.
    • Gentoo
    • FreeBSD, DragonFly BSD
  • Building from sources
    • Prerequisites
    • Installing dependencies
    • Downloading
    • Building
    • Installing
  • Usage
    • Sample output
    • Configuration
    • Different scan modes
    • Additional configuration steps for FreeBSD
    • Mounting and unmounting ClamFS file systems
• Fine tuning
  • Starting without clamd available
  • Mounting file systems from /etc/fstab
  • Using remote clamd instances
  • Read-only mounts
  • Program name reported as unknown when virus found
  • Using ClamFS with WINE
  • Installing FUSE v3 from sources
• License
• Historical repositories at SourceForge

Getting Started

These instructions will get you a copy of the project up and running on your local machine.

Installing packages

Arch

ClamFS package is available from AUR repository.

Debian, Ubuntu, etc.

Debian GNU/Linux, Ubuntu and Devuan have clamfs package in their repositories.

sudo apt install clamfs clamav-daemon clamav-freshclam

Gentoo

Gentoo provides sys-fs/clamfs package.

FreeBSD, DragonFly BSD

FreeBSD and DragonFly BSD has security/clamfs in ports.

Install package...

pkg install clamfs

... or install from ports.

cd /usr/ports/security/clamfs ; make install clean

Building from sources

Prerequisites

To build ClamFS on any GNU/Linux or *BSD you need:

• FUSE >= 3
• POCO >= 1.2.9
• Boost >= 1.33
• RLog
• pkg-config, autoconf, automake, make...

To run ClamFS clamd service from ClamAV project is required.

Note 1: POCO versions up to 1.2.8 contain 4-BSDL licensed files and thus you should avoid linking it against any GPL licensed code. I strongly advise using version 1.2.9 or newer (as license issues has been fixed).

Note 2: ClamFS version up to 1.0.1 required also GNU CommonCPP library. This dependency was dropped in version 1.1.0 (with commit 3bdb8ec).

Installing dependencies

Arch

Sync following packages to build ClamFS:

pacman -Syu base-devel fuse3 poco boost rlog

Debian, Ubuntu, etc.

To build ClamFS on Debian GNU/Linux and Ubuntu install these packages:

• libfuse3-dev
• libpoco-dev
• libboost-dev
• librlog-dev
• pkg-config

As a run-time dependency install:

• clamav-daemon
• fuse

Run following command to install all dependencies.

sudo apt-get -y --no-install-recommends install \
      build-essential pkg-config autoconf automake \
      libfuse3-dev libpoco-dev libboost-dev librlog-dev \
      clamav-daemon clamav-freshclam

Fedora

To build ClamFS on Fedora you need those packages:

• fuse3-devel
• poco-devel
• boost-devel
• rlog-devel
• pkg-config

As a run-time dependency install:

• clamd

Run following command to install all dependencies.

sudo dnf install automake rlog-devel boost-devel poco-devel fuse3-devel \
      pkg-config clamd

FreeBSD, DragonFly BSD

To build ClamFS on FreeBSD and DragonFly BSD you need those ports:

• sysutils/fusefs-libs3
• devel/poco
• devel/boost-libs
• devel/rlog
• devel/pkgconf
• devel/autoconf
• devel/automake

As a run-time dependency you need:

• security/clamav

Note: older FreeBSD version required port named sysutils/fusefs-kmod. This is no longer the case as fuse module is part of kernel.

Downloading

Just download the release package and extract it with tar.

tar xf clamfs-<version>.tar.gz

Or clone repository.

git clone https://github.com/burghardt/clamfs.git

Building

If using cloned repository rebuild autotools configuration with autogen.sh script. If using release tarballs skip this step.

sh autogen.sh

Configure package with configure script.

sh configure

Finally build sources with make.

make -j

Installing

Run make install (as root) to install binaries.

sudo make install

Usage

ClamFS requires only one argument - configuration file name. Configuration is stored as XML document. Sample configuration is available in doc directory, in file named clamfs.xml.

Sample output

17:11:44 (clamfs.cxx:993) ClamFS v1.1.0-snapshoot (git-7d4beda)
17:11:44 (clamfs.cxx:994) Copyright (c) 2007-2019 Krzysztof Burghardt <[email protected]>
17:11:44 (clamfs.cxx:995) https://github.com/burghardt/clamfs
17:11:44 (clamfs.cxx:1004) ClamFS need to be invoked with one parameter - location of configuration file
17:11:44 (clamfs.cxx:1005) Example: src/clamfs /etc/clamfs/home.xml

Configuration

Please refer to clamfs.xml for comprehensive list of configuration options. Only three options are mandatory:

• <clamd socket="" /> to set path to clamd socket
• <filesystem root="" /> to set place from ClamFS will read files
• <filesystem mountpoint="" /> to set mount point where virtual filesystem will be attached in directory tree

Different scan modes

ClamFS versions up to 1.1.0 use fname mode and pass only file name (with SCAN command) to clamd.

In ClamFS versions after 1.1.0 three different modes are available to pass files to clamd. Default method is fdpass.

mode="fname" - pass file name (with SCAN command)

This is the simplest mode. In this mode clamd opens and reads file by itself. Permissions have to be set to allow clamd to access the file. Also this mode works only when clamd and ClamFS are no the same machine and both have access to files. Using this mode might require permissions or ACLs setup for clamd user. Please note that attempts to run clamd as root to bypass permissions is usually a bad idea.

mode="fdpass" - pass file descriptor (with FILDES command)

This is the default mode when BSD 4.4 / RFC2292 style fd passing is available in the operating system. In this mode ClamFS opens file and passes file descriptor to clamd over UNIX domain socket. Finally clamd reads file by itself. This mode works only when clamd and ClamFS are no the same machine and operating system supports file descriptor sharing.

mode="stream" - pass file stream (with INSTREAM command)

Last mode offers ability to use remote clamd instances. In this mode ClamFS opens and reads file. Than sends it to clamd over the UNIX domain or TCP/IP socket. This works for local and remote clamd instances, but for local clamd instance fdpass is preferred scanning method.

Additional configuration steps for FreeBSD

FreeBSD's fuse kernel module has to be loaded before starting ClamFS. This can be done ad-hoc with kldload fuse command.

To have it loaded at boot time, add the following line to /boot/loader.conf.

fuse_load="YES"

Or append fuse module to kld_list in /etc/rc.conf.

kld_list="fuse"

Also configure ClamAV daemon and signature downloader service to start during boot with following options appended to /etc/rc.conf.

clamav_clamd_enable="YES"
clamav_freshclam_enable="YES"

Finally start required services with following commands.

service kld start
service clamav-freshclam start
service clamav-clamd start

Mounting and unmounting ClamFS file systems

To mount ClamFS filesystem run ClamFS with configuration filename as a parameter.

clamfs /etc/clamfs/netshare.xml

To unmount ClamFS use fusermount with -u flag and <filesystem mountpoint="/net/share" /> value as a parameter.

sudo fusermount -u /net/share

Fine tuning

Starting without clamd available

A new “check” option was added to allow you to mount a ClamFS file system when clamd is not available, such as during an early stage of the boot process. To disable ClamAV Daemon (clamd) check on ClamFS startup set option check to no:

<clamd socket="/var/run/clamav/clamd.ctl" check="no" />

Mounting file systems from /etc/fstab

With check=no mounting ClamFS file systems form /etc/fstab is possible using fuse mount helper (/sbin/mount.fuse). ClamFS will be started on boot with configuration file defined here provided as its argument. Simple definition of ClamFS mount point in /etc/fstab looks like:

clamfs#/etc/clamfs/share.xml  /clamfs/share  fuse  defaults  0  0

Using remote clamd instances

ClamFS can reach remote clamd instances using TCP/IP sockets. This type of connection requires mode="stream" settings and use clamd's INSTREAM command to scan files smaller than StreamMaxLength which defaults to 25 MiB.

<clamd socket="<IP>:<port>" mode="stream" />

Default clamd port is 3310. For server running at address 192.168.1.101 configuration is:

<clamd socket="192.168.1.101:3310" mode="stream" />

Read-only mounts

The “readonly” option was added to the filesystem options allowing you to create a read-only protected file system. Just extend filesystem definition in config file with readonly option set to yes:

<filesystem root="/share" mountpoint="/clamfs/share" readonly="yes" />

Program name reported as unknown when virus found

16:33:24 (clamav.cxx:152) (< unknown >:19690) (root:0) /tmp/eicar.com: Eicar-Test-Signature FOUND

To see program name instead of < unknown > in log messages on FreeBSD one need to mount /proc filesystem. Add following line to /etc/fstab.

proc /proc procfs rw 0 0

And mount /proc with mount /proc.

Program name should be reported correctly with mounted /proc.

16:37:31 (clamav.cxx:152) (hexdump:19740) (root:0) /tmp/eicar.com: Eicar-Test-Signature FOUND

Using ClamFS with WINE

Following steps setups on-access file scanning with ClamAV for WINE instance.

1. Install ClamFS runtime dependencies.

   sudo apt install clamav-freshclam clamav-daemon

2. Move original C:\ drive to new location.

   mv ~/.wine/drive_c ~/.wine/raw_drive_c
   mkdir ~/.wine/drive_c

3. Copy clamfs.xml to ~/.wine/clamfs.xml.
4. Set following options in clamfs.xml. Make sure mode="fdpass" and public="no" are set.

   <clamd socket="/var/run/clamav/clamd.ctl" mode="fdpass" check="yes" />
   <filesystem root="/home/user/.wine/raw_drive_c" mountpoint="/home/user/.wine/drive_c" public="no" />

5. Mount ClamFS filesystem as normal user with this command.

   clamfs ~/.wine/clamfs.xml

6. Run any WINE software and check logs with.

   sudo tail -F /var/log/clamav/clamav.log /var/log/syslog

For legacy configuration without mode=fdpass enabled please refer to my blog post Wine with on-access ClamAV scanning if you are interested in running ClamFS version <= 1.1.0 to protect WINE installation.

Installing FUSE v3 from sources

If your operating system does not provide binary package for libfuse3 (like Ubuntu 18.04 LTS) installing fuse3 from sources into /usr/local might be simplest method to install this dependency. Following commands installs current master branch from Github libfuse repository:

sudo apt-get -y --no-install-recommends install meson ninja-build
mkdir /tmp/fuse3 ; cd /tmp/fuse3
git clone --depth 1 https://github.com/libfuse/libfuse.git .
mkdir build ; cd build
meson ..
ninja
sudo ninja install

Please note that Debian 9 (codename "Stretch") is unable to build fuse3 as meson version provided in stretch repository is too old (package version is 0.37.1, but fuse requires >= 0.42).

License

This project is licensed under the GPLv2 License - see the COPYING file for details.

Historical repositories at SourceForge

Long time ago ClamFS was developed on SourceForge and some CVS and SVN repositories still resides there. Right now all development takes place on GitHub.