LATEST VERSION: 1.3 - RELEASE NOTES
File Integrity Monitoring Add-on for PCF v1.3

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 be a PCF operator with admin rights. See Operators in the Pivotal Cloud Foundry documentation.

  • You must have Ops Manager v2.0 or later.

Create the FIM Manifest

The FIM runtime configuration file is a YAML file that contains runtime configuration information for the FIM Add-on. Follow the steps below to create the FIM runtime configuration 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, enforce_cpu_limit, memory_limit, and heartbeat_interval. 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
        memory_limit: VALUE-OF-MEMORY-LIMIT-IN-BYTES
        heartbeat_interval: VALUE-OF-HEARTBEAT-INTERVAL
    ...
    

    cpu_limit:

    • Limits FIM to a percentage of available CPU resources when other processes are using CPU resources. Usage can exceed the limit if enough idle CPU cycles are available.
    • Must be set to a whole number less than 100. For example, set it 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 can 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.

    memory_limit:

    • Limits the maximum amount of user memory (including file cache) in bytes used by FIM.
    • Has the default value 536870912.

    heartbeat_interval:

    • To enable the heartbeat interval, set this value to an integer greater than 0 . If you set a negative value, an error occurs.
    • To disable the heartbeat interval, set this value to 0.
    • The default value is 600.

Download the FIM Add-on

To download the FIM Add-on software binary file and move it to your Ops Manager VM, follow 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, download FIM Add-on v1.2.22 or later.

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

  2. Copy the binary file to your Ops Manager VM by running 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.0.2.0:
  3. Copy the FIM runtime configuration fim.yml file to your Ops Manager instance by running 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.0.2.0:
  4. Log in to the Ops Manager VM with SSH.

  5. Navigate to the location of the binary file on the Ops Manager VM by running the following command:

    cd PATH-TO-BINARY-FILE
    

    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 file, 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 configuration to include the FIM Add-on, specifying the path to the fim.yml file you created earlier, 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 configuration into your existing add-on runtime configuration. Append the contents of fim.yml to your existing add-on YAML file.

  3. Verify that your runtime configuration 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 configuration. 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 in Configuring Logging in PAS. The syslog aggregator that you specify receives all alerts generated on PAS VMs, including the FIM alerts.
  • Using the syslog BOSH release: You can use the syslog BOSH release to forward system logs. See syslog-release in GitHub for instructions.

Note: When you configure syslog forwarding, ensure there is enough disk space for the logs. Make sure that the 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. Use bosh ssh to log in to one of the VMs in your deployment with SSH. For more information, see BOSH SSH.

  2. Run the following command:

    monit summary
    
  3. Look for the following process in the output:

    The Monit daemon 5.2.4 uptime: 3d 0h 56m
    Process 'fim'                 running
  4. If the fim process is not displayed, do the following:

    1. Start the fim process by running the following command:

      monit start fim
      
    2. Run the following command again:

      monit summary
      
    3. Check for the fim process again. If it does not display, check the /var/vcap/sys/log/fim logs for errors.

  5. If the fim process is displayed, do the following:

    1. Enter the following command:

      touch /bin/hackertool
      
    2. Enter the following command:

      grep hackertool /var/log/messages
      
  6. Check for a message that a new file has been created. For example:

    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