ClamAV Ansible Role¶

An Ansible role to install, configure, and manage ClamAV antivirus on Debian-based systems.

Features¶

• Installation and uninstallation of ClamAV and ClamAV daemon
• Configuration of ClamAV daemon (clamd)
• Configuration of virus database updater (freshclam)
• Automated daily database updates via systemd timer
• Service management (enable/disable/start/stop)
• Support for both local socket and TCP connections
• On-access scanning (real-time file system watcher) for monitoring specific directories

Installation¶

First add the following line to your requirements.yml file:

roles:
  - name: clamav
    src: https://gitlab.com/niclas-zone/tools/ansible/roles/clamav.git
    version: main
    scm: git

After that, we can install the role by executing the following command:

ansible-galaxy install -r requirements.yml --force

Role Variables¶

Core Configuration¶

ClamAV Daemon Configuration¶

Logging Configuration¶

Detection and Scanning Configuration¶

File System Configuration¶

Bytecode Configuration¶

Freshclam Configuration¶

Systemd Timer Configuration¶

Systemd Service Configuration¶

On-Access Scanning Configuration¶

Example Playbooks¶

Basic Installation¶

---
- hosts: linux-servers
  become: true
  roles:
    - role: clamav

Install with Custom Configuration¶

---
- hosts: linux-servers
  become: true
  roles:
    - role: clamav
      vars:
        clamav_daemon_enabled: true
        clamav_freshclam_enabled: true
        clamav_freshclam_daily_update: true
        clamav_freshclam_update_time: "02:00"
        clamav_daemon_tcp_socket: true
        clamav_daemon_tcp_port: 3310

Uninstall ClamAV¶

---
- hosts: linux-servers
  become: true
  roles:
    - role: clamav
      vars:
        clamav_state: absent

Disable Services Without Uninstalling¶

---
- hosts: linux-servers
  become: true
  roles:
    - role: clamav
      vars:
        clamav_daemon_enabled: false
        clamav_freshclam_enabled: false
        clamav_freshclam_daily_update: false

Enable On-Access Scanning (File System Watcher)¶

---
- hosts: linux-servers
  become: true
  roles:
    - role: clamav
      vars:
        clamav_onaccess_scanning_enabled: true
        clamav_onaccess_watch_paths:
          - /home
          - /var/www
        clamav_onaccess_exclude_paths:
          - /home/user/.cache
          - /var/www/tmp
        clamav_onaccess_max_threads: 5
        clamav_onaccess_prevention: false
        clamav_onaccess_extra_scanning: true

On-Access Scanning¶

On-access scanning allows ClamAV to monitor specific directories in real-time and scan files as they are accessed, created, or modified. This feature requires ClamAV to be running with appropriate permissions.

Key features:

• Real-time file system monitoring
• Configurable watch paths (directories to monitor)
• Configurable exclusion paths (directories to skip)
• Optional prevention mode (blocks access to infected files - requires kernel support)
• Extra scanning options (scan on open, close, and move operations)

Note: On-access scanning may impact system performance, especially on high-traffic directories. It's recommended to:

• Use specific watch paths rather than monitoring the entire filesystem
• Exclude cache directories, temporary directories, and system paths
• Start with prevention disabled and enable it only after testing
• Adjust the number of threads based on system resources

Daily Database Updates¶

This role creates a systemd timer (clamav-freshclam-daily.timer) that automatically updates the ClamAV virus database daily. The timer:

• Runs at the time specified by clamav_freshclam_update_time (default: daily)
• Has a randomized delay of up to 1 hour to prevent all linux-servers from updating at the same time
• Is persistent across reboots
• Can be disabled by setting clamav_freshclam_daily_update: false

You can check the timer status with:

systemctl status clamav-freshclam-daily.timer

View timer logs with:

journalctl -u clamav-freshclam-daily.service