LATEST VERSION: 1.3.4 - RELEASE NOTES
File Integrity Monitoring Add-on for PCF v1.3.4

Installing the FIM Add-on for PCF

Page last updated:

This topic describes how to install File Integrity Monitoring Add-on for PCF (FIM Add-on) on your Pivotal Cloud Foundry (PCF) deployment.

Prerequisites

Note: FIM Add-on does not work on Windows.

To complete the FIM installation:

  • You must use named runtime configs.

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

  • You must be a PCF operator with admin rights. See the Understanding Pivotal Cloud Foundry User Types topic for more information.

  • You must have Pivotal Operations Manager (Ops Manager) v2.0 or later.

Create the FIM Manifest

The FIM runtime config is a YML file that contains runtime configuration information for the FIM Add-on. Follow the steps below to create the FIM runtime config for your deployment:

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

    releases:
    - name: fim
      version: X.X.X
    addons:
    - name: fim-trusty
      jobs:
      - name: fim
        release: fim
        properties: {}
      include:
        stemcell:
        - os: ubuntu-trusty
    - name: fim-xenial
      jobs:
      - name: fim
        release: fim
        properties:
          fim:
            dirs:
              # System binaries and configuration
              - /bin
              - /etc
              - /lib
              - /lib32 # xenial-specific
              - /lib64
              - /opt
              - /sbin
              - /srv
              - /usr
              - /var/lib
    
              # Bosh agent
              - /var/vcap/bosh
              - /var/vcap/monit/job
    
              # Bosh releases
              - /var/vcap/data/packages
              - /var/vcap/data/jobs
      include:
        stemcell:
        - os: ubuntu-xenial
    
  2. (Optional) Set the properties cpu_limit and enforce_cpu_limit. To use these properties, place the following text under the fim subsection of fim.yml, as shown below:

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

    cpu_limit:

    • Limits FIM 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 FIM 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, verify that cpu_limit is set high enough for FIM to execute normally. If the limit is too strict, FIM fails to start.

Download the FIM Add-on

To download the FIM Add-on software binary file and move it to your Ops Manager virtual machine (VM), perform the steps below. If you intend to run the FIM Add-on on a PCF deployment that includes services or components that use Ubuntu Xenial stemcells, you should download FIM Add-on v1.2.22 or later.

WARNING! Ensure that you are using named runtime configs. For more information, see Prerequisites.

  1. Download the FIM 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 fim-release.tgz ubuntu@YOUR-OPS-MANAGER-VM-IP:
    

    For example:

    $ scp -i ~/.ssh/my-key.pem fim-1.2.23.tar.gz ubuntu@192.168.0.2:
  3. To copy the FIM runtime config, fim.yml file, to your Ops Manager instance, run the following command:

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

    For example:

    $ scp -i ~/.ssh/my-key.pem fim.yml ubuntu@192.168.0.2:
  4. SSH into the Ops Manager VM. For how to do this, see SSH into Ops Manager.

  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 ~

Deploy the FIM Add-on

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

  1. Upload your release, specifying the path to the tarballed FIM binary, by running the following command:

    bosh -e BOSH-ENVIRONMENT upload-release PATH-TO-NEW-FIM-RELEASE
    

    For example:

    $ bosh -e my-env upload-release fim-1.2.23.tar.gz
  2. Update your runtime config to include the FIM Add-on, specifying the path to the fim.yml file you created above, by running the following command:

    bosh -e BOSH-ENVIRONMENT update-runtime-config --name=fim /tmp/fim.yml
    

    For example:

    $ bosh -e my-env update-runtime-config --name=fim fim.yml

    Note: If you installed other BOSH add-ons, you must merge the FIM runtime config into your existing add-on runtime config. Append the contents of fim.yml to your existing add-on YML file.

  3. Verify that your runtime config changes match what you specified in the manifest file.

    bosh -e BOSH-ENVIRONMENT runtime-config --name fim
    

    For example:

    $ bosh -e my-env runtime-config --name=fim
    

    This command returns your updated FIM runtime config. For example:

    Acting as user 'admin' on 'micro'
    releases:
    - name: fim
      version: 1.2.23
    addons:
      name: fim
        jobs:
        - name: fim
          release: fim
    ...
    
  4. Navigate to the Installation Dashboard in Ops Manager.

  5. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  6. Click Apply Changes.

Configure Forwarding for FIM Alerts

The FIM 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.

  • Using the Pivotal Application Service (PAS) tile: Follow the steps to Configure System Logging in PAS. The syslog aggregator that you specify receives all alerts generated on PAS VMs, including the FIM alerts.
  • Using the BOSH syslog release: You can use the syslog BOSH release to forward system logs. See the syslog-release for instructions.

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 the Installation

  1. BOSH SSH into one of the VMs in your deployment.

  2. Run monit summary. Look for the following processes in the output:

    The Monit daemon 5.2.4 uptime: 3d 0h 56m
    Process 'fim'                 running
  3. If monit summary does not list fim, perform the following steps:

    1. Start the FIM processes by running the following commands:
      $ monit start fim
      
    2. Run monit summary again. If you do not see the processes mentioned above, check /var/vcap/sys/log/fim logs for errors.
  4. If monit summary does list fim, do the following:

    1. Enter the following commands:
      $ touch /bin/hackertool
      $ grep hackertool /var/log/messages
    2. Look for a message that a new file has been created:
      Sep 22 23:57:07 qvsfgv0qnrk filesnitch[3040]: CEF:0|cloud_foundry|fim|1.0.0|1|file integrity monitoring event|5| fname="/bin/hackertool" hostname="f98968fe-501a-470b-819a-c4a2a7ac45c8" opname="CREATE" optype=1 ts=1474588627
Create a pull request or raise an issue on the source for this page in GitHub