- You will need the UpGuard real-time forwarder, and the permissions to install it.
- You will need a Windows connection manager at version 4.8.13 or higher.
- At time of writing, the UpGuard real-time forwarder is only supported on the following operating systems (all 64-bit):
- Windows 2008
- Windows 2008 R2 SP1
- Windows 2008 SP2
- Windows 2008 R2
- Windows 2012
- Windows 2012 R2
The UpGuard real-time forwarder (henceforth simply “the forwarder”) can be installed via one of two methods: manual installation via MSI, or remote installation from the appliance.
Installation via MSI
To install the forwarder via MSI, simply download the installer here and follow the prompts.
Installation from the Appliance
Remote installation of the forwarder is accomplished using WinRM for Windows nodes. Windows nodes that you wish to install the forwarder on remotely will need to use the WinRM connection type in UpGuard.
To install the forwarder from the appliance, you will need administrative credentials for the nodes to which you wish to connect.
- Log into UpGuard.
- Select the nodes you wish to install the forwarder on using the checkbox to the left of each row.
From the dropdown above the node list, select “Install Real-time Driver”.
You will be prompted to enter credentials for a user account with sufficient privileges to install software remotely using WinRM.
The installation process will commence. You can track its progress via the presented modal, or from the job history page.
If the installation process completes successfully, you must initiate a node scan to finalize the setup of the forwarder. This first scan will determine if the forwarder is running and in a health state, and if so, will push any existing real-time filter options to it so that it can commence event collection.
Once such a scan has been run, setup is complete, as indicated by the “RT” badge that will now be present against the node records on the “Monitored” page.
Once you have installed the forwarder on a node, you will need to configure the directories that you would like to track for file changes. This is done by adding file scan options as per usual, but indicating that you would like the information to be collected in real-time via the “Real-time” checkbox.
Entries in these lists may be absolute paths to files or directories, or they may be glob-based paths that cover one or more files (just like normal scan options). Any files not explicitly covered by a whitelist will not be monitored in real-time.
So as not to overwhelm the node visualisation with a potentially vast number of files, scan options marked as "Real-time" will not populate the node visualisation (the events will still be tracked via the regular event system though). To have a CI record present in the visualisation to associate events with, simply add a normal, non-"Real-time" scan option that covers the files you are looking for. If the files that you wish to cover are exactly in line with those specified in a "Real-time" scan option, then you will need to specify those options against a secondary node group that the node is apart of.
Whitelisting vs Blacklisting
The forwarder accepts a whitelist and a blacklist that define the files that will be monitored. To whitelist an item, simply enter a path in for the scan option and ticket the “Real-time” checkbox. To blacklist and item, follow the same procedure, then check the “Blacklist” checkbox in the “Advanced” section under the scan option. As per usual, the whitelist defines files that will be monitored, while the blacklist defines those that will not, overriding the whitelist where appropriate.
Viewing Real-time Events
Real-time events for files can be viewed from one of two locations: on the visualization for the node, and on the events page.
Files on real-time enabled nodes may have their standard configuration information supplemented by real-time events. These events will be presented on the attribute panel for the node, along with a “View All RTF Events” button allowing you to view RTF events on the events page.
Real-time events may also be viewed on the events page, either as part of the unfiltered event stream or more specifically by filtering to events with a type of “Configuration Change”.
Filtering of real-time events may be performed using any of the variables present on on the event, but the most common event variable filters will include:
- path: The file path of the file to which the event pertains
- process_name: The name of the process that made the change
- username: The name of the user that made the change
While it is fine for dynamic filtering, it is generally not recommended to create event views based on the timestamp variable.
To uninstall the forwarder, simply go to “Programs and Features” and choose the “Uninstall” option for the “UpGuard Real Time Forwarder”.
A system restart may be required to fully uninstall the forwarder.
RTF log files
Any errors generated by the forwarder will be logged in a file on the target machine, and collected when the forwarder’s events are processed. However, these logs are cleared on a set basis, rather than per-scan; as such, any errors in the log will be presented until the logs are rotated out. If you experience errors that reference the forwarder specifically coming back with your node scans, contact UpGuard support to have them addressed.
unknown process def: install_fim
If you receive the above error when attempting to install the forwarder, you have either attempted to install the forwarder on a non-Windows node or with a version of the Windows connection manager that does not support it.
Error loading filter library
If you receive the above error when running a node scan, then the connection manager that was attempting to update the filter options associated with that particular forward was unable to do so. To troubleshoot, confirm that the forwarder service is running on the target node, and if not restart it. If it is running, contact UpGuard support.