Geneos File Agent - User Guide

Introduction

The Geneos File Agent is a lightweight data collection process which runs on an application server, and forwards log data onwards to a separate process for monitoring. This separation is intended to minimise the impact on the application server machine, so as to avoid impacting performance of the monitored process.

image1

Figure 1 - File Agent architecture

At present a single File Agent process can serve data to a single data consuming process at a time. Supported data consumers at this time include:

  • Fix-analyzer 2

For a resilient configuration, multiple consumers can be configured to connect to the same agent so that failure of the connected consumer will cause a failover to the waiting consumer.

This guide is concerned with installing and running the File Agent. Instructions on configuration of the File Agent can be found in the reference guide for the consumer process (e.g. the Fix Analyser 2 reference guide). This is because the File Agent literally acts as an agent: names, locations and matching rules of the files to be read are all configured in the consumer and the agent merely acts upon this instruction.

Installing File Agent

List of Supported Platforms

For the list of supported platforms, see 5.x Compatibility Matrix.

Downloading and Installing (Linux)

The File Agent is available as a tar.gz archive. To install the agent on Linux, unpack the tar.gz file with the following commands:

gunzip <archive>.tar.gz
tar -xvf <archive>.tar

Once unpacked the tar file is no longer needed and can be removed.

If this is a new installation of the agent, simply place the unpacked files in the directory from which the agent is to be launched.

If upgrading from an earlier version then stop the agent, replace all of the files with those from the new version, and then restart the agent. To remove the agent, remove all file contents of the directory where the tar.gz archive was unpacked.

When Security-Enhanced Linux (SELinux) is running in Enforcing mode, it may deny certain functions of Geneos depending on the implemented configurations and policies.

To see which functions SELinux denies, check the audit log. The log is typically located in /var/log/audit.log, where the log type entry is AVC. The audit log provides the details of any denied access. For example, denied connection to the TCP port.

If you experience issues related to this mode, you may opt to disable SELinux, or create policy modules to grant the required access. Please contact your administrator or security team for assistance.

Downloading and Installing (Windows)

The File Agent is optionally available for Windows as an installer binary. When run the File Agent will be installed as a service. The default name for the service is "GeneosFileAgent" and the default port is 7030. These defaults can be changed when you run the installer.

If you do not want the agent to start automatically as a service whenever Windows is started, open the Services control panel, find and double-click the row for Geneos File Agent and change the startup type to Manual in the Properties dialog.

To uninstall the agent, use the Windows "Add or remove programs" feature. Log files will not be deleted when the uninstaller is run; this is intentional, but means that if you want to remove the directory into which you installed the agent, you may need to do so manually.

Running File Agent

On Windows, the File Agent can be run either by starting the agent service or by executing the "agent.windows.exe" binary from the command line. On Linux, the agent is run by executing the "agent.linux_64" binary from the command line.

Running from the command line

Linux

$ ./agent.linux_64
$ ./agent.linux_64 -port 18008

See below for information about the available command line options.

Windows

>agent.windows.exe
>agent.windows.exe -port 18008

See below for information about the available command line options.

If you intend to run the agent from the Windows command line, ensure that it is not set to run automatically as a service. (See section Downloading and Installing (Windows) above)

Command line options

File Agent accepts the following command line options:

-port <port_number>

The port on which the File Agent listens for Netprobe connections. This option overrides the PORT environment variable, if this is set. (See Listen port below)

-log <file_name>

The name of a file to which the File Agent should write its log output (see below). This option overrides the LOG_FILENAME environment variable, if this is set. (See Log file below)

-nolog

Send log output to standard output. This option overrides the LOG_FILENAME environment variable, if this is set.

-help

Prints the File Agent usage message. Can be abbreviated to -h

-version

Prints File Agent version information. Can be abbreviated to -v

-cmd

Provided for consistency with the Geneos Netprobe on Windows. Indicates that the program should be run as a command and not as a service. As this is the default behaviour for File Agent, manually specifying this option is not required.

-run, -install, -remove, -uninstall

These options are used when the File Agent is run, installed or uninstalled as a Windows service. They should not be used when running the program from the command line.

Listen port

By default the File Agent listens for connections by consumer processes on TCP port 7030. This value can be overridden by:

  • Specifying a different port number during installation (Windows only).
  • Altering the value of the \HKEY_LOCAL_MACHINE\SOFTWARE\GeneosAgents\serviceName\PORT registry key (Windows only). On 64-bit versions of Windows, this will be located in \HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\GeneosAgents\serviceName\PORT.
  • Defining the PORT environment variable.
  • Specifying the -port command line option.

Log file

The File Agent produces log output during normal operation. If the agent is run from the command line, messages will be directed to standard output. If the agent is run as a Windows service, the log file will be written to "file-agent.log" in the agent installation directory, unless a different path was specified during installation.

The default log file behaviour can be overridden by:

  • Defining the environment variable LOG_FILENAME.
  • Altering the value of the \HKEY_LOCAL_MACHINE\SOFTWARE\GeneosAgents\serviceName\LOG_FILENAME registry key (Windows only). On 64-bit versions of Windows, this is located in \HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\GeneosAgents\serviceName\LOG_FILENAME.
  • Specifying the -log or -nolog command-line options.

For more information on environment variables, see Netprobe variables.

Running as a Windows Service

You can start and stop the File Agent service using the Services control panel. You should ensure that the "Startup Type" column in the Services control panel shows Automatic if you want the agent service to run every time Windows is rebooted.

Files Included in the File Agent Package

The following table is a summary of the contents of the File Agent package according to platform.

Linux platforms Solaris Sparc Solaris x64 IBM AIX Windows
agent.linux_64 agent.sun_64 agent.sunx86_64 agent.aix_64 agent.windows.exe
lib64/libssl.so lib64/libssl.so lib64/libssl.so lib64/libssl.so fileagentinst.bat
lib64/libssl.so.1.0.0 lib64/libssl.so.1.0.0 lib64/libssl.so.1.0.0 lib64/libssl.so.1.0.0 fileagentuninst.bat
lib64/libcrypto.so lib64/libcrypto.so

lib64/libcrypto.so

lib64/libcrypto.so

libeay32.dll

lib64/libcrypto.so.1.0.0

lib64/libcrypto.so.1.0.0

lib64/libcrypto.so.1.0.0

lib64/libcrypto.so.1.0.0

msvcp100.dll

templates/start_file_agent.tmpl

templates/start_file_agent.tmpl

templates/start_file_agent.tmpl

msvcr100.dll
  pthreadVC.dll

ssleay32.dll

unins000.dat
unins000.exe

The following table provides the description and use of each file listed above.

File Description
agent.aix_64 The main AIX File Agent binary.
agent.linux_64 The main Linux File Agent binary.
agent.sun_64 The main Solaris Sparc File Agent binary.
agent.sunx86_64 The main Solaris X86 File Agent binary.
agent.windows.exe The main Windows File Agent binary.
fileagentinst.bat Used by the installer to create a File Agent service.
fileagentuninst.bat Used by the installer to stop and remove a File Agent service.
libeay32.dll OpenSSL library, required by libcurl.dll to provide cryptographic functions for authentication.
libssl.so* OpenSSL library, required by libcurl.so to provide support for HTTPS URLs.
libcrypto.so* OpenSSL library, required by libcurl.so to provide cryptographic functions for authentication.
msvcp100.dll Microsoft Visual C++ Runtime library.
msvcr100.dll Microsoft Visual C++ Runtime library.
pthreadVC.dll Threading support DLL.
ssleay32.dll OpenSSL library, required by libcurl.dll to provide support for HTTPS URLs.
unins000.dat Uninstaller support file (see below).
unins000.exe Uninstaller; the digits 000 may vary if more than one program is installed to the same directory.
templates/start_file_agent.tmpl Template for a start script to run File Agent.

By default, the File Agent log file, file-agent.log, will also be created in the installation directory.