Foglight Agent Manager 7.3.0 - Foglight Agent Manager Guide

Configuring the target (monitored) system

Recent versions of Windows® OS include WinRM, but it is disabled by default. There are two ways to configure HTTP or HTTPS: manually or using Group Policy Objects.

IMPORTANT: Payload-level encryption encrypts only the contents of the messages that are exchanged between the Agent Manager and the monitored system. It does not affect the security of any credentials passed between the target system and the Agent Manager. If you require full encryption, configure the WinRM server to use HTTPS. HTTPS safely and securely encrypts all data transmitted between the Agent Manager and the monitored system.

The default WinRM settings allow only Negotiate authentication.

NOTE: You can enable Basic authentication without disabling Negotiate authentication. Some systems can have both Negotiate and Basic authentication enabled, in that order of preference. If Negotiate authentication fails, a Basic authentication request is attempted.

TIP: To enable or disable either Basic or Negotiate authentication, use the following command syntax: winrm set winrm/config/service/auth @{<Basic|Negotiate>="<true|false>"}

If additional security is required, for example if data is transferred across untrusted networks, you can configure WinRM to use HTTPS. A valid server authentication certificate must be installed on the target machine in order to enable HTTPS.

NOTE: You cannot use self-signed certificates. NOTE: The target machine is required to enable TLSv1.2 when it is monitored via WinRM HTTPS in FIPS-compliant mode.

The certificate must be granted by a recognized certificate-granting authority (CA) in order for the Agent Manager to authenticate it. Otherwise you must install the root CA certificate in the Agent Manager’s trusted keystore, as described in Installing HTTPS certificates.

TIP: Install the certificates in the following location: Certificates (Local computer)/Personal/Certificates

You can use Windows Group Policy Objects to automatically configure HTTP or HTTPS listeners in WinRM. Enable or disable the appropriate default group policies that are pre-installed with Windows, or use the defaults as a template to develop new policies.

In environments where an in-house certificate granting authority (CA) is in use, the CA’s certificate must be added to the Agent Manager’s trust keystore. The Agent Manager then assumes that the authority, and any signed certificates it issues, are trusted.

Configuring the Agent Manager (monitoring) system

The Agent Manager automatically attempts to perform the necessary configuration on the monitoring host machine. If for any reason the changes cannot be made, you have to manually update the following settings.

The WinRM Negotiate authentication scheme uses Kerberos. By default, the Agent Manager searches the following files for information about the location of the Key Distribution Center (KDC):

If the Agent Manager fails to find a configuration file, it attempts to automatically detect the required settings and writes them to $FGLAM/state/default/config/krb5.config.

NOTE: The fglam.config.xml file specifies the location of the krb5 file in the <kerberos‑config‑file> element. If the element is empty or omitted, no configuration file is used.

You can manually override the location of krb5 file with the following command-line parameter:

-Djava.security.krb5.conf=</path/to/file>

Generating a configuration file required for WinRM Negotiate authentication

WinRM connections using the default Negotiate authentication require a copy of the krb5.config file. The Agent Manager attempts to auto-generate this file and places it under <fglam_home>/state/default/config/krb5.config.

If the file needs to be created, the format of the krb5.config file for the WinRM Negotiate authentication is as follows:

Where:

The values dns_suffix_upper_case, dns_suffix_lower_case, and DNS_Server_for_dns_suffix_upper_case must be replaced with their actual values.

The [domain_realm] section in the file maps the domain of the host being connected to, to a realm.

The [realm] section provides the relevant kdc (key distribution center) server with a specific realm to use for kerberos authentication. This is generally the DNS server for the relevant domain.

The default_realm value in the libdefaults section is the realm mapping to use when the domain of the host cannot be matched to a realm.

For example, for connecting to hosts on the sample.domain.com domain with the dnsserver.sample.domain.com DNS Server, the contents of the krb5.config file should be as follows:

When connecting to a host1.sample.domain.com, the host1’s domain is mapped to the SAMPLE.DOMAIN.COM realm, which maps to the DNSSERVER.SAMPLE.DOMAIN.COM kdc to use for kerberos authentication.

After the krb5.config file is created the absolute path to the generated krb5.config file should be provided in the <config:krb5-config-file> tag value of the <fglam_home>/state/default/config/fglam-config.xml file, so that it can be accessed by the Agent Manager. Any changes to the fglam-config.xml file require the Agent Manager to be restarted in order for those changes to take effect. Therefore, if the Agent Manager is running while you are making these changes, you must restart it.

Additional registry keys may be required when you deploy an Agent Manager on a Windows host. The Agent Manager installer attempts to make the changes automatically. If the Agent Manager is unable to establish a WinRM connection, check that the following changes were made correctly.

The KerberosConfigurationService API provides the ability for agents to modify or create a Kerberos configuration file during runtime.

The Agent Manager uses the Kerberos configuration file to establish WinRM Negotiate connections to hosts. In most cases, the Agent Manager can create the Kerberos configuration for the current domain to which the machine running the Agent Manager belongs. However, the Kerberos configuration typically needs to be modified when cross-domain WinRM connections are required. This can be done by modifying the Kerberos configuration file manually, to add the new domain properties, and restarting the Agent Manager. If no instance of the previous Kerberos configuration file is found, the fglam.config.xml file needs to be updated to instruct the Agent Manger which Kerberos configuration file to use for WinRM connections.

All of these actions can also be performed during runtime, without requiring any manual changes, or an Agent Manager restart. The KerberosConfigurationService allows agents to make these changes during runtime and have the changes take effect immediately. If a new configuration file is created, fglam.config.xml file is updated automatically.

For complete information about this service, see the Foglight Agent Manager Devkit and Javadoc documentation.

Configuring command-shell connection settings

WinRM relies on a set of configuration parameters that establish the level of system resources the WinRM service needs to address incoming requests. In certain cases, some parameter values do not provide sufficient configuration levels which can lead to run-time errors.

Depending on how WinRM is used, some parameter values may not provide sufficient configuration levels which can lead to connection issues. The Agent Manager makes an attempt to diagnose some of these situations and communicate appropriate recommendations using Warning messages. The configuration levels that the Agent Manager attempts to diagnose are:

TIP: WinRM parameters can also be edited using the Group Policy Object Editor. To start the editor, type gpedit.msc at the command line, and then navigate to Local Computer Policy > Computer Configuration > Administrative templates > Windows Components > Windows Remote Management (WinRM) and Windows Remote Shell.

For additional information, visit the following Web page:

http://msdn.microsoft.com/en-us/library/windows/desktop/aa384372%28v=vs.85%29.aspx