1# ClamFS 2ClamFS - User-space fs with on-access antivirus scanning 3 4## Description 5 6ClamFS is a [FUSE-based user-space file system](https://en.wikipedia.org/wiki/Filesystem_in_Userspace) 7for Linux and [BSD](https://www.freshports.org/security/clamfs/) 8with on-access anti-virus file scanning through [clamd daemon](https://manpages.debian.org/testing/clamav-daemon/clamd.8.en.html) 9(a file scanning service developed by [ClamAV Project](https://www.clamav.net/)). 10 11## Features 12 13 * User-space file system (no kernel patches, recompilation, etc.) 14 * Configuration stored in XML files 15 * FUSE (and libfuse) used as file system back-end 16 * Scan files using ClamAV 17 * ScanCache (LRU with time-based and out-of-memory expiration) speeds up file access 18 * Sends mail to administrator when detect virus 19 20## Getting Started 21 22These instructions will get you a copy of the project up and running on your 23local machine. 24 25### Installing packages 26 27#### Arch 28 29[ClamFS package](https://aur.archlinux.org/packages/clamfs/) 30is available from [AUR](https://aur.archlinux.org/) repository. 31 32#### Debian, Ubuntu, etc. 33 34[Debian GNU/Linux](https://packages.debian.org/clamfs), 35[Ubuntu](https://packages.ubuntu.com/clamfs) and 36[Devuan](https://pkginfo.devuan.org/cgi-bin/d1pkgweb-query?search=clamfs) 37have `clamfs` package in their repositories. 38 39``` 40sudo apt install clamfs clamav-daemon clamav-freshclam 41``` 42 43#### Gentoo 44 45Gentoo provides [sys-fs/clamfs package](https://packages.gentoo.org/packages/sys-fs/clamfs). 46 47#### FreeBSD, DragonFly BSD 48 49[FreeBSD](https://www.freshports.org/security/clamfs/) and [DragonFly BSD]() has `security/clamfs` in ports. 50 51Install package... 52``` 53pkg install clamfs 54``` 55 56... or install from ports. 57``` 58cd /usr/ports/security/clamfs ; make install clean 59``` 60 61### Building from sources 62 63#### Prerequisites 64 65To build ClamFS on any GNU/Linux or *BSD you need: 66 * [FUSE](https://github.com/libfuse/libfuse) 67 * [RLog](https://www.arg0.net/rlog) 68 * [POCO](https://pocoproject.org/) 69 * [Boost](https://www.boost.org/) 70 71To run ClamFS `clamd` service from [ClamAV project](https://www.clamav.net/) 72is required. 73 74Note 1: POCO versions up to 1.2.8 contain 4-BSDL licensed files and thus you 75should avoid linking it against any GPL licensed code. I strongly advise using 76version 1.2.9 or newer (as license issues has been fixed). 77 78Note 2: ClamFS version up to 1.0.1 required also 79[GNU CommonCPP](https://www.gnu.org/software/commoncpp/) 80library. This dependency was dropped in version 1.1.0 (with commit 3bdb8ec). 81 82#### Installing dependencies 83 84##### Debian, Ubuntu, etc. 85 86To build ClamFS on Debian GNU/Linux and Ubuntu install these packages: 87 * libfuse-dev 88 * librlog-dev 89 * libpoco-dev 90 * libboost-dev 91 92As a run-time dependency install: 93 * clamav-daemon 94 * fuse 95 96Run following command to install al dependencies. 97``` 98sudo apt-get -y --no-install-recommends install \ 99 build-essential automake libfuse-dev \ 100 librlog-dev libpoco-dev libboost-dev \ 101 clamav-daemon clamav-freshclam 102``` 103 104##### FreeBSD, DragonFly BSD 105 106To build ClamFS on FreeBSD and DragonFly BSD you need those ports: 107 * sysutils/fusefs-libs 108 * devel/rlog 109 * devel/poco-ssl (or devel/poco) 110 * devel/boost-libs 111 112As a run-time dependency you need: 113 * security/clamav 114 115Note: older FreeBSD version required port named `sysutils/fusefs-kmod`. 116This is no longer the case as `fuse` module is part of kernel. 117 118#### Downloading 119 120Just download the release package and extract it with `tar`. 121 122``` 123tar xf clamfs-<version>.tar.gz 124``` 125 126Or clone repository. 127 128``` 129git clone https://github.com/burghardt/clamfs.git 130``` 131 132#### Building 133 134If using cloned repository rebuild autotools configuration with `autogen.sh` 135script. If using release tarballs skip this step. 136``` 137sh autogen.sh 138``` 139 140Configure package with `configure` script. 141``` 142sh configure 143``` 144 145Finally build sources with `make`. 146``` 147make -j 148``` 149 150#### Installing 151 152Run `make install` (as root) to install binaries. 153``` 154sudo make install 155``` 156 157### Usage 158 159ClamFS requires only one argument - configuration file name. Configuration is 160stored as XML document. Sample configuration is available in `doc` directory, 161in file named [clamfs.xml](doc/clamfs.xml). 162 163#### Sample output 164 165``` 16617:11:44 (clamfs.cxx:993) ClamFS v1.1.0-snapshoot (git-7d4beda) 16717:11:44 (clamfs.cxx:994) Copyright (c) 2007-2019 Krzysztof Burghardt <krzysztof@burghardt.pl> 16817:11:44 (clamfs.cxx:995) https://github.com/burghardt/clamfs 16917:11:44 (clamfs.cxx:1004) ClamFS need to be invoked with one parameter - location of configuration file 17017:11:44 (clamfs.cxx:1005) Example: src/clamfs /etc/clamfs/home.xml 171``` 172 173#### Configuration 174 175Please refer to [clamfs.xml](doc/clamfs.xml) for comprehensive list of 176configuration options. Only three options are mandatory: 177 * `<clamd socket="" />` to set path to `clamd` socket 178 * `<filesystem root="" />` to set place from ClamFS will read files 179 * `<filesystem mountpoint="" />` to set mount point where virtual filesystem 180 will be attached in directory tree 181 182#### Additional configuration steps for FreeBSD 183 184FreeBSD's `fuse` kernel module has to be loaded before starting ClamFS. This 185can be done ad-hoc with `kldload fuse` command. 186 187To have it loaded at boot time, add the following line to `/boot/loader.conf`. 188``` 189fuse_load="YES" 190``` 191 192Or append fuse module to `kld_list` in `/etc/rc.conf`. 193``` 194kld_list="fuse" 195``` 196 197Also configure ClamAV daemon and signature downloader service to start during 198boot with following options appended to `/etc/rc.conf`. 199``` 200clamav_clamd_enable="YES" 201clamav_freshclam_enable="YES" 202``` 203 204Finally start required services with following commands. 205``` 206service kld start 207service clamav-freshclam start 208service clamav-daemon start 209``` 210 211#### Mounting and unmounting ClamFS file systems 212 213To mount ClamFS filesystem run ClamFS with configuration filename as a parameter. 214``` 215clamfs /etc/clamfs/netshare.xml 216``` 217 218To unmount ClamFS use `fusermount` with `-u` flag and 219`<filesystem mountpoint="/net/share" />` value as a parameter. 220``` 221sudo fusermount -u /net/share 222``` 223 224## Fine tuning 225 226### Starting without clamd available 227 228A new “check” option was added to allow you to mount a ClamFS file system when 229clamd is not available, such as during an early stage of the boot process. 230To disable ClamAV Daemon (clamd) check on ClamFS startup set option check to 231no: 232``` 233<clamd socket="/var/run/clamav/clamd.ctl" check="no" /> 234``` 235 236### Mounting file systems from /etc/fstab 237 238With `check=no` mounting ClamFS file systems form /etc/fstab is possible using 239fuse mount helper (/sbin/mount.fuse). ClamFS will be started on boot with 240configuration file defined here provided as its argument. Simple definition 241of ClamFS mount point in /etc/fstab looks like: 242``` 243clamfs#/etc/clamfs/share.xml /clamfs/share fuse defaults 0 0 244``` 245 246### Read-only mounts 247 248The “readonly” option was added to the filesystem options allowing you to 249create a read-only protected file system. Just extend filesystem definition 250in config file with `readonly` option set to `yes`: 251``` 252<filesystem root="/share" mountpoint="/clamfs/share" readonly="yes" /> 253``` 254 255### Program name reported as unknown when virus found 256 257``` 25816:33:24 (clamav.cxx:152) (< unknown >:19690) (root:0) /tmp/eicar.com: Eicar-Test-Signature FOUND 259``` 260 261To see program name instead of `< unknown >` in log messages on FreeBSD one 262need to mount `/proc` filesystem. Add following line to `/etc/fstab`. 263``` 264proc /proc procfs rw 0 0 265``` 266And mount `/proc` with `mount /proc`. 267 268Program name should be reported correctly with mounted `/proc`. 269``` 27016:37:31 (clamav.cxx:152) (hexdump:19740) (root:0) /tmp/eicar.com: Eicar-Test-Signature FOUND 271``` 272 273### Using ClamFS with WINE 274 275Please refer to my blog post [Wine with on-access ClamAV scanning](https://blog.burghardt.pl/2007/11/wine-with-on-access-clamav-scanning/) 276if you are interested in running ClamFS to protect WINE installation. 277 278## License 279 280This project is licensed under the GPLv2 License - see the 281[COPYING](COPYING) file for details. 282 283## Historical repositories at SourceForge 284 285Long time ago [ClamFS](http://clamfs.sourceforge.net/) was developed on 286[SourceForge](https://sourceforge.net/projects/clamfs/) and some CVS and 287SVN repositories still resides there. Right now all development takes place 288on GitHub. 289