Implementing real-time virus scanning on Linux via ClamAV is a critical security requirement for modern cloud and industrial infrastructure. This ClamAV Installation Guide focuses on moving beyond reactive scheduled scans toward proactive, kernel-level threat mitigation using the ClamOnAcc (ClamAV On-Access) service. In industrial environments such as Water Treatment Control Systems or Energy Grid Management, a single malicious payload can disrupt critical logic controllers. This manual provides the architectural framework to integrate automated threat detection directly into the Linux file system. By leveraging the Fanotify kernel subsystem, we ensure that a file is scanned for malicious signatures before its execution or modification is permitted. This prevents the lateral movement of ransomware and provides an idempotent security layer across highly distributed network nodes. The solution addresses the specific problem of high-latency manual audits by automating threat remediation at the point of ingestion; effectively reducing the window of vulnerability between file arrival and system infection.
TECHNICAL SPECIFICATIONS (H3)
| Requirement | Default Port/Operating Range | Protocol/Standard | Impact Level (1-10) | Recommended Resources |
| :— | :— | :— | :— | :— |
| ClamAV Engine | Local Unix Socket / Port 3310 | POSIX / IEEE 1003.1 | 8 | 2.5GB+ RAM (Sig DB) |
| Fanotify Subsystem | Kernel Internal | Linux Kernel 5.x+ | 9 | Support for O_MAYEXEC |
| Freshclam service | Port 443 (HTTPS) | TLS 1.2/1.3 | 4 | Minimal (CPU Burst) |
| Log Rotation | /var/log/clamav/ | Syslog / RFC 5424 | 3 | Consistent Disk I/O |
| ClamOnAcc | Kernel Watch Points | Fanotify API | 7 | 1-2 Total CPU Cores |
THE CONFIGURATION PROTOCOL (H3)
Environment Prerequisites:
Successful deployment requires elevated root permissions and a Linux kernel compiled with CONFIG_FANOTIFY and CONFIG_FANOTIFY_ACCESS_PERMISSIONS enabled. Most modern enterprise distributions such as RHEL 8/9, Ubuntu 22.04 LTS, and Debian 12 include these by default. Ensure the system has at least 4GB of physical RAM to accommodate the visual signature database without triggering the Out Of Memory (OOM) killer. The environment must allow outbound HTTPS traffic to database.clamav.net for signature updates. Failure to provide sufficient memory will lead to high latency during engine initialization and potential service crashes.
Section A: Implementation Logic:
The architectural design rests on the separation of the scanning engine (clamd) and the file system monitoring agent (clamonacc). The clamd daemon remains resident in memory; it holds the entire virus signature database in a pre-compiled state to minimize lookup latency. When a user-space application attempts to access a file, the Fanotify kernel hook intercepts the system call. The clamonacc client receives this event and passes the file descriptor to clamd via a local Unix socket. The engine analyzes the payload for malware patterns. If the file is clean, the kernel is notified to proceed with the access. If a threat is detected, the kernel denies the access request, effectively blocking the malware before it can execute.
Step-By-Step Execution (H3)
1. Repository Synchronization and Package Installation
Execute apt-get update && apt-get install clamav clamav-daemon clamav-freshclam on Debian-based systems or dnf install clamav clamd clamav-update on RHEL-based systems.
System Note: This process registers the necessary binaries and creates the clamav system user. It populates the /etc/clamav/ directory with default configuration templates that require immediate modification for real-time functionality.
2. Manual Signature Database Initialization
Stop the update service using systemctl stop clamav-freshclam and manually trigger an update by running freshclam.
System Note: The signature update involves downloading large CVD (ClamAV Virus Database) files. Running this manually for the first time ensures that the clamd service can start with a valid database. This step is idempotent; if the database is already current, freshclam will exit without making redundant changes, preserving network throughput.
3. Configuring the ClamDaemon Path
Open /etc/clamav/clamd.conf and ensure the LocalSocket variable is set to /var/run/clamav/clamd.ctl. Locate the User directive and set it to root temporarily for Fanotify access; or more securely, configure specific capabilities.
System Note: ClamAV requires the ability to call the Fanotify API. Running the daemon as a non-privileged user without specific Linux Capabilities will result in a permission-denied error at the kernel level. This configuration sets the communication bridge for all subsequent scan requests.
4. Activating Real-Time Scanning Directives
Edit /etc/clamav/clamd.conf to include the following lines: OnAccessMaxFileSize 100M, OnAccessIncludePath /home, and OnAccessPrevention yes.
System Note: These variables define the scope of the real-time monitor. The OnAccessPrevention flag is the most critical; it instructs the kernel to block file access until the scan is complete. This introduces a slight disk I/O overhead but ensures total encapsulation of the file session.
5. Launching the ClamOnAcc Client
Enable and start the services using systemctl enable –now clamav-daemon followed by the manual execution of clamonacc.
System Note: The clamonacc binary acts as the bridge between the Fanotify kernel events and the clamd scanner. When it starts, it registers watches on the directories specified in the configuration. This increases the kernel memory footprint slightly to maintain the watch list.
6. Verification of Kernel Hooks
Monitor the logs using tail -f /var/log/clamav/clamav.log while attempting to create a test file in the protected path.
System Note: Use a non-malicious EICAR test string to verify the block. The log should show a “found” event followed by an “Access denied” message from the kernel. This confirms that the signal-attenuation between the user-space and kernel-space is functioning correctly.
Section B: Dependency Fault-Lines:
The most frequent point of failure is a mismatch between the clamd socket location and where clamonacc expects to find it. If the socket path is missing, clamonacc will fail to initialize. Another common bottleneck is the maximum number of Fanotify marks. If you attempt to monitor too many directories, you may hit the fs.fanotify.max_user_marks limit. This can be resolved by increasing the value in /etc/sysctl.conf. Additionally, if the system experiences high thermal-inertia or CPU throttling, the scanning latency might exceed the application’s timeout for file access, leading to “I/O Error” messages in the application layer.
THE TROUBLESHOOTING MATRIX (H3)
Section C: Logs & Debugging:
When a service fails, primary diagnostic data is found in /var/log/clamav/clamav.log and /var/log/clamav/freshclam.log. If clamonacc refuses to start, check the kernel ring buffer using dmesg | grep fanotify.
| Error String | Likely Root Cause | Resolution Path |
| :— | :— | :— |
| Can’t connect to clamd on LocalSocket | clamd service is stopped | systemctl restart clamav-daemon |
| Fanotify: Permission denied | Insufficient Capable Privileges | Set User root in clamd.conf |
| Malformed database | Interrupted download | Delete main.cvd and rerun freshclam |
| Socket file exists | Leftover pid/socket | Remove /var/run/clamav/clamd.ctl manually |
| OOM Killer: Killed process | Memory Exhaustion | Increase Swap or RAM; Reduce DB size |
Analyze the clamav.log for “ScanOnAccess: Could not watch” messages. This typically indicates a path does not exist or the kernel cannot mount a watch point on a network-mounted file system (NFS/SMB). ClamAV real-time scanning is most stable on local ext4 or xfs partitions; scanning remote mounts can lead to significant packet-loss or network-induced latency.
OPTIMIZATION & HARDENING (H3)
– Performance Tuning: Use the OnAccessExcludeUname directive to exclude trusted users like backup agents or database engines. This reduces the total concurrency load on the clamd engine and lowers the overall CPU overhead. Pinning the clamd process to a specific CPU core using taskset can prevent the scanner from interfering with time-sensitive industrial control software.
– Security Hardening: Apply AppArmor or SELinux profiles to the clamd process. Ensure that the /etc/clamav/ directory is owned by root with 644 permissions to prevent unauthorized modification of the virus scan exclusions. Use a dedicated partition for logs to prevent a log-burst from consuming the entire system root partition.
– Scaling Logic: In a high-traffic cluster, do not run the database update on every node simultaneously. Set up a local private mirror using clamav-mirror to distribute the signature files. This reduces the external bandwidth consumption and ensures that every node in the infrastructure uses a synchronized, idempotent version of the signature database.
THE ADMIN DESK (H3)
How do I check if real-time scanning is active?
Run ps aux | grep clamonacc. Additionally, check the status via systemctl status clamav-daemon. If the process is running and the logs show “Watching” entries for your target directories, the system is actively intercepting file system calls.
Why is ClamAV using 100 percent of my CPU?
During the initial startup or after a large signature update, clamd reloads its database. This is a CPU-intensive task. Once the database is loaded into RAM, usage should drop to minimal levels until a file access triggers a scan.
Can I scan files larger than 2GB?
Yes, but you must adjust the MaxFileSize and MaxScanSize settings in clamd.conf. Be aware that scanning very large files in real-time introduces significant access latency, which may cause applications to time out or crash.
How do I exclude a directory from scanning?
Use the OnAccessExcludePath directive in /etc/clamav/clamd.conf. This is essential for directories containing large database files or high-frequency logs where the overhead of a virus scan would negatively impact the system throughput and disk performance.
