- 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.
- The UpGuard real-time forwarder is only supported on the following Windows 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 is only supported on the following Linux operating systems:
- Amazon Linux
- CentOS 5
- CentOS 6
- CentOS 7
- Debian 8
- Debian 9
- Oracle Linux 6
- Oracle Linux 7
- RHEL 6
- RHEL 7
- Ubuntu 12.04 (32 and 64 bit)
- Ubuntu 14.04
- Ubuntu 16.04
- Ubuntu 18.04
The UpGuard real-time forwarder (henceforth simply “the forwarder”) can be installed via one of two methods: manual installation via MSI (Windows only), or remote installation from the appliance (Windows and Linux).
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 and SSH for Linux nodes.
To install the forwarder from the appliance, you will need administrative credentials (username and password) for the nodes to which you wish to connect. These credentials are used in a one-time fashion and are not stored after use.
- 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 Forwarder”.
You will be prompted to enter credentials for a user account with sufficient privileges to install software remotely.
The installation process will commence. You can track its progress via the presented modal, or from the job history page found under Control > Job History.
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.
For more detailed information on scan options, please visit our guide on Scan Options.
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 visualization with a potentially vast number of files, scan options marked as "Real-Time" will not populate the node visualization (the events will still be tracked via the regular event system under Control > Events). To have a CI record present in the visualization to associate events with, simply add a second 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 a part 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 on Windows, 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.
Otherwise, you can also uninstall the forwarder from Windows or Linux via the Appliance interface. Simply select the node or nodes you wish to uninstall the forwarded from and click Uninstall Real-Time Forwarded in the drop down menu.
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 node that does not support the Forwarder or with a version of the 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.