LATEST VERSION: 1.4 - CHANGELOG
ClamAV Add-on for PCF v1.4

ClamAV Add-on for PCF

Page last updated:

This topic describes how to add ClamAV to your Pivotal Cloud Foundry (PCF) deployment.

About ClamAV Add-on for PCF

This add-on may be necessary for regulatory purposes if your compliance auditor requires antivirus protection within the PCF environment.

For example, auditors sometimes expect that antivirus protection is present in an environment that must comply with standards such as Payment Card Industry Data Security Standard (PCI DSS) or Health Insurance Portability and Accountability Act (HIPAA).

Feature Snapshot

The following table provides version and version-support information about the ClamAV Add-on for PCF.

Element Details
Version v1.4.28
Release date June 28, 2018
Compatible Ops Manager version(s) v1.7 or later
Compatible Elastic Runtime version(s) v1.7 or later
Compatible Pivotal Application Service (PAS)* version(s) v1.7 or later
IaaS support vSphere, GCP, AWS, Azure, and Openstack

Prerequisites

To install ClamAV Add-on, you need:

  • Named runtime configs (for PCF v1.11 or later).

    If you have not already split your runtime config into multiple named files, do so before installing or upgrading the ClamAV Add-on for PCF. For general information about named runtime config files, see Configs.

  • A PCF operator with admin rights. For more information, see Understanding Pivotal Cloud Foundry User Types.

  • Operations Manager (Ops Manager) v1.7 or later.

  • At least 1 GB of memory free on each VM before deploying ClamAV Add-on. ClamAV Add-on uses 610 MB of memory.

  • A local mirror to get ClamAV virus updates. For instructions on how to set up a local mirror, see Private Local Mirrors in the ClamAV documentation.

Note: Release version x.x.x in the clamav.yml samples below is arbitrary. Replace it with the version of ClamAV release downloaded from PivNet.

Create the ClamAV Manifest

The ClamAV manifest is a YML file that contains runtime config information for ClamAV Add-on. To create the ClamAV manifest for your deployment, follow the steps below:

clamav.yml Template for Linux

  1. Create a file named clamav.yml, using the following code as a template.

    releases:
    - name: clamav
      version: x.x.x
    addons:
    - name: clamav
      jobs:
      - name: clamav
        release: clamav
        properties:
          clamav:
            database_mirror: 192.0.2.1
      include:
        stemcell:
        - os: ubuntu-trusty
    
  2. (Optional) Set the properties cpu_limit and enforce_cpu_limit. To use these properties, place the following text under the clamav subsection of clamav.yml, as shown below:

    ...
    properties:
      clamav:
        cpu_limit: VALUE-OF-CPU-LIMIT
        enforce_cpu_limit: TRUE|FALSE
    ...
    

    cpu_limit:

    • Limits ClamAV to a percentage of available CPU resources when other processes are using CPU resources. Usage may exceed the limit if enough idle CPU cycles are available.
    • Set to a whole number less than 100. For example, set to 50 to limit ClamAV to 50% CPU usage when other tasks are running.
    • The default value is 10.

    enforce_cpu_limit:

    • When true, the limit set by cpu_limit is always enforced.
    • When false, the limit set by cpu_limit is only enforced when other processes are using CPU resources. Usage may exceed the limit if enough idle CPU cycles are available.
    • This property is false by default.

    WARNING: If enforce_cpu_limit is set true, ensure cpu_limit is set high enough for ClamAV to execute normally. If the limit is too strict, ClamAV fails to start. For example, an n1-standard VM on GCP requires cpu_limit to be > 45.

clamav.yml Template for Windows

Create a file named clamav.yml using the following code as a template.

releases:
- name: clamav
  version: x.x.x
addons:
- name: clamav-windows
  jobs:
  - name: clamav-windows
    release: clamav
    properties:
      clamav:
        database_mirror: 192.0.2.1
  include:
    stemcell:
    - os: windows2012R2

General clamav.yml Template Configuration

  1. In the database_mirror field of the template, provide the hostname or IP address of a private ClamAV update mirror. Environments that cannot connect to the internet should use an update mirror. If you do not specify a value, ClamAV defaults to an S3-based mirror for updates. For compliance reasons, only use the S3-based mirror in non-production environments.

    For instructions on how to set up a local mirror, see Private Local Mirrors in the ClamAV documentation.

  2. (Optional) If you have to use a proxy server to connect to the internet, add the proxy_host and proxy_port properties to your manifest.

    If the proxy server needs authentication, add the proxy_user and proxy_password properties, as shown below:

    releases:
    - name: clamav
        version: x.x.x
    addons:
       - name: clamav
        jobs:
        - name: clamav
            release: clamav
       properties:
         clamav:
            proxy_host: PROXY.LOCALDOMAIN
            proxy_port: PROXY-PORT
            proxy_user: PROXY-USERNAME
            proxy_password: PROXY-SECRET
    ...
    

Download ClamAV Add-on

To download the ClamAV Add-on software binary and move it to the Ops Manager VM, do the following:

WARNING! If you are using PCF v1.11 or later, ensure that you are using named runtime configs. For more information, see Prerequisites.

  1. Download the ClamAV Add-on software binary from the Pivotal Network to your local machine.

  2. To copy the binary to your Ops Manager VM, run the following command:

    scp -i PATH-TO-PRIVATE-KEY clamav-release.tar.gz ubuntu@YOUR-OPS-MANAGER-VM-IP:
    

    For example:

    $ scp -i ~/.ssh/my-key.pem clamav-1.3.28.tar.gz ubuntu@192.168.0.2:  
  3. To copy the ClamAV manifest, clamav.yml file, to your Ops Manager instance, run the following command:

    scp -i PATH-TO-PRIVATE-KEY clamav.yml ubuntu@YOUR-OPS-MANAGER-VM-IP:
    

    For example:

    $ scp -i ~/.ssh/my-key.pem clamav.yml ubuntu@192.168.0.2:  
  4. To SSH into Ops Manager, run the following command:

    ssh -i PATH-TO-PRIVATE-KEY ubuntu@YOUR-OPS-MANAGER-VM-IP
    

    For example:

    $ ssh -i ~/.ssh/my-key.pem ubuntu@192.168.0.2
  5. To navigate to the location of the binary on the Ops Manager VM, run the following command:

    cd PATH-TO-BINARY
    

    For example:

    $ cd ~/clamav-1.3.28.tar.gz

Deploy the ClamAV Add-on

Perform the following steps to deploy the ClamAV Add-on:

  1. Log in to the BOSH Director.

    • For Ops Manager v1.10 or earlier: On the Ops Manager VM, target your BOSH Director instance. For example:
      $ bosh target 10.0.0.3
      Target set to 'Ops Manager'
      Your username: director
      Enter password: ******************
      Logged in as 'director'
      
    • For Ops Manager v1.11:
      1. On the Ops Manager VM, create an alias in the BOSH CLI for your BOSH Director IP address. For example:
        $ bosh2 alias-env my-env -e 10.0.0.3
      2. Log in to the BOSH Director, specifying the newly created alias. For example:
        $ bosh2 -e my-env log-in
    • For Ops Manager v1.12 or later:
      1. On the Ops Manager VM, create an alias in the BOSH CLI for your BOSH Director IP address. For example:
        $ bosh alias-env my-env -e 10.0.0.3
      2. Log in to the BOSH Director, specifying the newly created alias. For example:
        $ bosh -e my-env log-in
  2. Upload your release, specifying the path to the tarballed ClamAV binary, by running one of the following commands:

    For Ops Manager v1.10 or earlier:
    $ bosh upload release ~/clamav-1.3.28.tar.gz

    For Ops Manager v1.11:
    $ bosh2 -e my-env upload-release ~/clamav-1.3.28.tar.gz

    For Ops Manager v1.12 or later:
    $ bosh -e my-env upload-release ~/clamav-1.3.28.tar.gz

  3. List the releases by running one of the following commands, and confirm that ClamAV appears:

    For Ops Manager v1.10 or earlier:
    $ bosh releases

    For Ops Manager v1.11:
    $ bosh2 -e my-env releases

    For Ops Manager v1.12 or later:
    $ bosh -e my-env releases

  4. Update your runtime configuration to include the ClamAV Add-on, specifying the path to the clamav.yml file you created above, by running one of the following commands:

    Note: If you installed other BOSH add-ons, you must merge the ClamAV manifest into your existing add-on manifest. Append the contents of clamav.yml to your existing add-on YML file.


    For Ops Manager v1.10 or earlier:
    $ bosh update runtime-config ~/clamav.yml

    For Ops Manager v1.11:
    $ bosh2 -e my-env update-runtime-config --name=clamav ~/clamav.yml

    For Ops Manager v1.12 or later:
    $ bosh -e my-env update-runtime-config --name=clamav ~/clamav.yml

  5. Verify that your runtime configuration changes match what you specified in the ClamAV manifest by running one of the following commands:

    For Ops Manager v1.10 or earlier:
    $ bosh runtime-config

    For Ops Manager v1.11:
    $ bosh2 -e my-env runtime-config

    For Ops Manager v1.12 or later:
    $ bosh -e my-env runtime-config

    For Example:
    $ bosh -e my-env runtime-config
    Acting as user 'admin' on 'micro'
    releases:
    - name: clamav
       version: 1.0.0
    
    addons: name: clamav jobs: - name: clamav release: clamav ...

  6. Navigate to your Installation Dashboard in Ops Manager.

  7. Click Apply Changes.

Configure Forwarding for ClamAV Alerts

The ClamAV BOSH release writes all alerts to the syslogs of the VMs in your deployment. You can use syslog forwarding to forward the alerts to a syslog aggregator.

Follow the steps to Configure System Logging in the Pivotal Application Service (PAS) or Elastic Runtime tile. The syslog aggregator that you specify receives all alerts generated on PAS (or Elastic Runtime) VMs, including the ClamAV alerts.

Note: When you configure syslog forwarding, ensure there is enough disk space for the logs. Make sure that log rotation is frequent enough. If in doubt, rotate the logs hourly or when they reach a certain size. Pivotal recommends forwarding logs to a remote syslog aggregation system.

Verify Your ClamAV Add-on Installation

  1. BOSH SSH into one of the VMs in your deployment. If you are using PCF v1.11 or later, use the BOSH CLI v1. If you are using PCF v1.10 or earlier, use the BOSH CLI v2.
  2. Run monit summary. Look for the following processes in the output:
    The Monit daemon 5.2.4 uptime: 3d 0h 56m
    Process 'clamd'                     running
    Process 'freshclam' running
  3. If monit summary does not list clamd and freshclamd, do the following:
    1. Try to start the ClamAV processes by running the following commands:
        $ monit start clamd
      $ monit start freshclam
    2. Run monit summary again. If you do not see the processes mentioned above, check /var/vcap/sys/log/clamav logs for errors.
  4. If monit summary does list freshclamd and clamd, create a file in /var/vcap on the VM with the following contents:
    X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
    
    This is a virus signature used to test anti-virus software.

After clamdscan completes, a notification should appear in /var/log/syslog. This scan can take up to an hour.

ClamAV Log Format

ClamAV log format is unstructured. If a virus is detected, the following text is sent to syslog:

Jul 11 17:36:35 k2lam76scmb clamd[3022]: SelfCheck: Database status OK
Jul 11 17:42:34 k2lam76scmb clamd[3022]: /bin/infected-file: Eicar-Test-Signature FOUND

A generalized format for the logline is:

clamd[PID]: INFECTED-FILE-PATH: VIRUS-NAME FOUND

Enable On-Access Scan

Note: On-Access Scan is not supported on Windows.

ClamAV offers immediate file scanning upon file modification. This feature may reduce the time it takes to detect and report malware.

Enable the feature with the on_access runtime config property:

  1. In the clamav.yml file, add the on_access property under the clamav property, set on_access to yes, shown in bold:
    
      releases:
      - name: clamav
          version: x.x.x
      
    addons: name: clamav jobs: - name: clamav release: clamav properties: clamav: on_access: yes scheduled: yes ...
  2. Apply changes by updating your runtime config as described in Download and Deploy ClamAV Add-on.

Configure Scheduled Scan

ClamAV can be configured to run a virus scan hourly or daily, with hourly scan being the default.

To change the scheduled scan to run daily:

  1. In the clamav.yml file, add the property schedule_interval under the clamav property, and set it to daily, as shown below:

   releases:
   - name: clamav
       version: x.x.x
   
addons: name: clamav jobs: - name: clamav release: clamav properties: clamav: schedule_interval: daily scheduled: yes ...
2. Apply changes by updating your runtime config as described in Download and Deploy ClamAV Add-on.

Disable Scheduled Scan

To disable the scheduled scan, do the following:

  1. In the clamav.yml file, set the property scheduled to no.
  2. Apply changes by updating your runtime config as described in Download and Deploy ClamAV Add-on.

Choose the Action on Infected Files

You can configure ClamAV to take action when infected files are found. By default, a notification is sent to the syslog when an infected file is found. However, you can specify other actions, as described in step 2 below.

  1. In the clamav.yml file, add the action property under the clamav property and, optionally, the action_destination property, shown in bold:

    releases:
    - name: clamav
        version: x.x.x
    
    addons:
      name: clamav
        jobs:
          - name: clamav
            release: clamav
        properties:
          clamav:
            action: <strong>ACTION</strong>
            action_destination: <strong>PATH</strong>
    ...
    
  2. Replace ACTION with one of the following values:

    • notify: The default, only send a notification to syslog
    • remove: Delete the infected file from the filesystem
    • move: Move the infected file to the directory location specified by action_destination
    • copy: Copy the infected file to the directory location specified by action_destination

    If you don’t supply an action, the function fails.

  3. Replace PATH with the directory location where you want the infected files moved or copied to. The system does not scan the moved-to or copied-to location. If the directory path is not valid, the function fails.

    Example configuration:

    releases:
    - name: clamav
        version: x.x.x
    
    addons:
      name: clamav
        jobs:
          - name: clamav
            release: clamav
        properties:
          clamav:
            action: move
            action_destination: /var/vcap/data/clamav/found
      ...
    
Create a pull request or raise an issue on the source for this page in GitHub