Virus Scanner Support
Overview
ClamAV is the only officially supported virus scanner available for use with ownCloud. It:
-
Operates on all major operating systems, including Windows, Linux, and macOS
-
Detects all forms of malware including Trojan horses, viruses, and worms
-
Scans compressed files, executables, image files, Flash, PDF, as well as many others
What’s more, ClamAV’s Freshclam daemon automatically updates its malware signature database at scheduled intervals. However, other scanners can be used, so long as they:
-
Can receive data streams via pipes on the command-line and return an exit code.
-
Return a parseable result on stdout.
How ClamAV Works With ownCloud
ownCloud integrates with antivirus tools by connecting to them via:
-
A URL and port
-
A socket
-
Streaming the data from the command-line via a pipe with a configured executable
In the case of ClamAV, ownCloud’s Antivirus extension sends files as streams to a ClamAV service (which can be on the same ownCloud server or another server within the same network) which in turn scans them and returns a result to stdout.
| Individual chunks are not scanned. The whole file is scanned when it is moved to the final location. |
The information is then parsed, or an exit code is evaluated if no result is available to determine the response from the scan. Based on ownCloud’s evaluation of the response (or exit code) an appropriate action is then taken, such as recording a log message or deleting the file.
| Scanner exit status rules are used to handle errors when ClamAV is run in CLI mode. Scanner output rules are used in daemon/socket mode. |
Things To Note
-
Files are checked when they are uploaded or updated (whether because they were edited or saved) but not when they are downloaded.
-
ownCloud doesn’t support a cache of previously scanned files.
-
If the app is either not configured or is misconfigured, then it rejects file uploads.
-
If ClamAV is unavailable, then the app rejects file uploads.
-
A file size limit applies both to background jobs and to file uploads.
Configuring the ClamAV Antivirus Scanner
You can configure your ownCloud server to automatically run a virus scan on newly-uploaded files using the Antivirus App.
| ClamAV must be installed before installing and configuring Antivirus App for Files. |
Installing ClamAV
As always, Linux distributions install and configure ClamAV in different ways. Below you can find the instructions for installing it on Debian or Red Hat-based distributions.
Debian, Ubuntu, Linux Mint
Install ClamAV on Debian, Ubuntu — and their many variants — with the following command:
sudo apt install clamav clamav-daemon
This automatically creates the default configuration files and launches the clamd and freshclam daemons.
You shouldn’t have to do anything else, though it is a good idea to review the ClamAV documentation, as well as ClamAV’s settings in /etc/clamav/.
Red Hat 7 and CentOS 7
On Red Hat 7 and related systems, you must install the Extra Packages for Enterprise Linux (EPEL) repository, and then install ClamAV.
To do so, run the following commands:
yum install epel-release
yum install clamav clamav-scanner clamav-scanner-systemd clamav-server
clamav-server-systemd clamav-update
Regardless of the operating system, we recommend that you enable verbose logging in both clamd.conf and freshclam.conf until you get any kinks with your ClamAV installation worked out.
|
Configuring and Running ClamAV
After installing ClamAV and the related tools, you will now have two configuration files: /etc/freshclam.conf and /etc/clamd.d/scan.conf.
You must edit both of these before you can run ClamAV.
Both files are well commented.
Running either man clamd.conf or man freshclam.conf provides detailed information on all the available configuration options.
Refer to /etc/passwd and /etc/group when you need to verify the ClamAV user and group.
|
When you’re finished editing the configuration files, you must enable the clamd service file and start clamd.
You can do so using the following commands:
systemctl enable clamav-daemon.service
systemctl start clamav-daemon.serviceWhen successful, output similar to the following renders to the console:
Synchronizing state of clamav-daemon.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable clamav-daemonConfigure the Port
To configure the port that ClamAV listens on, add the following line in /etc/clamav/clamd.conf:
TCPSocket 3310Then, restart the ClamAV daemon as follows:
sudo /etc/init.d/clamav-daemon restart
Enable verbose logging in scan.conf and freshclam.conf until it is running the way you want.
|
Automating ClamAV Virus Database Updates
To update your malware database and get the latest malware signatures, you need to run freshclam frequently.
Do this by running freshclam or sudo freshclam on Debian-based distributions.
We recommend you do this, post-installation, to download your first set of malware signatures.
If you want to adjust freshclam’s behavior, edit /etc/clamav/freshclam.conf and make any changes you believe are necessary.
After that, create a cron job to automate the process. For example, to run it every hour at 47 minutes past the hour, add the following in the applicable user’s crontab:
# m h dom mon dow command 47 * * * * /usr/bin/freshclam --quiet
| Please avoid any multiples of 10, because those are when the ClamAV servers are hit the hardest for updates. |
Install the Anti-Virus App
The Anti-Virus app needs to be installed from the ownCloud Market (it’s available in the _ "Security"_ category). You can access the ownCloud Market via the App Menu (or App Switcher).
| The Anti-Virus app can also be downloaded, installed, and enabled manually. |
Configuring ClamAV within ownCloud
| If the app is enabled but either not configured or incorrectly configured it will strictly reject all uploads for the whole instance |
ClamAV can be configured in two ways:
Configure ClamAV Using occ
All of the configuration settings for ClamAV are configurable by passing the relevant key and value to the occ config:app:set files_antivirus command.
For example:
sudo -u www-data php occ config:app:set \
files_antivirus av_socket --value="/var/run/clamav/clamd.ctl"Available Configuration Settings
| Setting | Description | Default |
|---|---|---|
|
Extra command line options (comma-separated) to pass to ClamAV. |
|
|
The hostname or IP address of the Antivirus server. |
|
|
The action to take when infected files were found during a background scan.
It can be set to one of |
|
|
The maximum file size limit; |
|
|
The operating mode. It can be set to one of |
|
|
The path to the |
|
|
The port number of the Antivirus server. Allowed values are 1 - 65535. |
|
|
The name of ClamAV’s UNIX socket file. |
|
|
The maximum stream length that ClamAV will accept. |
|
Configure ClamAV Using The Antivirus Configuration Panel
Once ClamAV is installed, select and, in the "Log" section, set Log level to "Everything (fatal issues, errors, warnings, info, debug)".
Now, navigate to , where you’ll find the "Antivirus Configuration" panel. There, as below, you’ll see the configuration options which ownCloud passes to ClamAV.
Mode Configuration
ClamAV runs in one of three modes:
Daemon (Socket)
In this mode, ClamAV runs in the background on the same server as the ownCloud installation, or the socket can be made available via a share mount.
When there is no activity, clamd places a minimal load on your system.
However, if your users upload large volumes of files, you will see high CPU usage.
Please keep this in mind.
You must run freshclam at least once for ClamAV to generate the socket.
|
First, set Mode to "Daemon (Socket)".
ownCloud should detect your clamd socket and fill in the "Socket" field.
This is the LocalSocket option in clamd.conf.
You can run netstat to verify it, as in the example below:
sudo ss -a | grep -iq clamav && echo "ClamAV is running"|
If you don’t have |
The Stream Length value sets the number of bytes to read in one pass; 10485760 bytes (ten megabytes) is the default.
This value should be no larger than the PHP memory_limit settings or physical memory if memory_limit is set to -1 (no limit).
When infected files were found during a background scan gives you the choice of either:
-
Logging any alerts without deleting the files
-
Immediately deleting infected files
Daemon
In this mode, ClamAV runs on a different server. This is a good option for ownCloud servers with high volumes of file uploads.
First, set Mode to "Daemon". Then, you need to set Host to the hostname or IP address of the remote server running ClamAV, and set Port to the server’s port number.
The port number is the value of TCPSocket in /etc/clamav/clamd.conf.
|
Executable
In this mode, ClamAV runs on the same server as the ownCloud installation, with the clamscan command running only when a file is uploaded.
clamscan is slow and not always reliable for on-demand usage; it is better to use one of the daemon modes.
|
First, set Mode to "Executable".
Then, set Path to clamscan to the path to clamscan, which is the interactive ClamAV scanning command, on your server.
ownCloud should automatically find it.
However, if it doesn’t, run which clamscan to find the command’s path.
When you are satisfied with how ClamAV is operating, you might want to go back and change all of your logging to less verbose levels.
Configuration Warnings
The Antivirus App shows one of three warnings if it is misconfigured or ClamAV is not available. You can see an example of all three below.
What To Do With Infected Files Found During Scans
When infected files are detected during a scan, the app can take one of two actions:
-
Only log: Log the event.
-
Delete file: Delete the detected file.
Set When infected files were found during a background scan to the value that suits your needs.
Rule Configuration
ownCloud provides the ability to customize how it reacts to the response given by an antivirus scan. To do so, under click Advanced, which you can see in the screenshot below, you can view and change the existing rules. You can also add new ones.
Rules can match on either an exit status (e.g., 0, 1, or 40) or a pattern in the string returned from ClamAV (e.g., /.: (.) FOUND$/).
Here are some points to bear in mind about rules:
-
Scanner exit status rules are used to handle errors when ClamAV is run in CLI mode while
-
scanner output rules are used in daemon/socket mode.
-
Daemon output is parsed by regexp.
-
In case there are no matching rules, the status is:
Unknown, and a warning will be logged.
Default Ruleset
The default rule set for ClamAV is populated automatically with the following rules:
| Exit Status or Signature | Description | Marks File As |
|---|---|---|
0 |
Clean |
|
1 |
Infected |
|
40 |
Unknown option passed |
Unchecked |
50 |
Database initialization error |
Unchecked |
52 |
Not supported file type |
Unchecked |
53 |
Can’t open directory |
Unchecked |
54 |
Can’t open file |
Unchecked |
55 |
Error reading file |
Unchecked |
56 |
Can’t stat input file |
Unchecked |
57 |
Can’t get absolute path name of current working directory |
Unchecked |
58 |
I/O error |
Unchecked |
62 |
Can’t initialize logger |
Unchecked |
63 |
Can’t create temporary files/directories |
Unchecked |
64 |
Can’t write to temporary directory |
Unchecked |
70 |
Can’t allocate memory (calloc) |
Unchecked |
71 |
Can’t allocate memory (malloc) |
Unchecked |
|
Clean |
|
|
Infected |
|
|
Unchecked |
The rules are always checked in the following order:
-
Infected
-
Error
-
Clean
In case there are no matching rules, the status would be Unknown and a warning would be logged.
Update An Existing Rule
To match on an exit status, change the "Match by" dropdown list to "Scanner exit status" and in the "Scanner exit status or signature to search" field, add the status code to match on.
To match on the scanner’s output, change the "Match by" dropdown list to "Scanner output" and in the "Scanner exit status or signature to search" field, add the regular expression to match against the scanner’s output.
Then, while not mandatory, add a description of what the status or scan output means. After that, set what ownCloud should do when the exit status or regular expression you set matches the value returned by ClamAV. To do so change the value of the dropdown in the "Mark as" column.
The dropdown supports the following three options:
| Option | Description |
|---|---|
Clean |
The file is clean and contains no viruses |
Infected |
The file contains a virus |
Unchecked |
No action should be taken |
With all these changes made, click the check mark on the left-hand side of the "Match by" column, to confirm the change to the rule.
Add A New Rule
To add a new rule, click the button marked Add a rule at the bottom left of the rules table. Then follow the process outlined in Update An Existing Rule.