IBM Endpoint Manager, Version 9.0

Setting up a proxy connection

If your enterprise uses a proxy to access the Internet, you must set a proxy connection to enable the IBM Endpoint Manager server to gather content from sites.

The proxy connection is also used by the IBM Endpoint Manager server or a relay to do component-to-component communication or to download files.

The following configurations are the most common proxy configurations that you might need to set up:

The IBM Endpoint Manager server must connect to the Internet through a proxy to gather content.

To set this configuration, which is run on the server, complete the steps that are described in Setting a proxy connection on the server. On Windows systems, the debug tool informs you if the communication through a proxy does not work.

Important: Skipping this step would prevent your environment from working properly. A symptom of this misbehavior is that the site contents are not displayed on the console.

A relay needs to connect to the Internet through a proxy to download files and to communicate with its parent relay.

To set this configuration, which is run on the relay, complete the steps that are described in Setting up a proxy connection on a relay.

A client needs to connect to the Internet through a proxy to communicate with its parent relay.

To set this configuration, complete the following steps:

Run on the relay the steps that are described in Setting up a proxy connection on a relay.
Run on the client the steps that are described in Setting up a proxy connection on a client or a child relay using the console.

A relay needs to connect to the Internet through a proxy to communicate with a child relay.

To set this configuration, complete the following steps:

Run on the parent relay the steps that are described in Setting up a proxy connection on a relay.
Run on the child relay the steps that are described in Setting up a proxy connection on a client or a child relay using the console.

For information about the settings that you can use to configure your IBM Endpoint Manager environment, see configure the server in the knowledge base at the IBM Endpoint Manager support site.

Note: You can also maintain a physical disconnect from the Internet with an air-gapped implementation. For more information about this implementation, see Downloading files in air-gapped environments.

The steps to follow to configure the communication through a proxy are different depending on whether you set up the configuration for the first time on an IBM Endpoint Manager version 9.0 Patch 5 or on an earlier version.

The following tables list, for each component, the steps to complete to set up the proxy configuration on version 9.0 Patch 5 or later.

Table 1. . Steps to configure communication through a proxy on an IBM Endpoint Manager server
Server
Linux	Windows
In the besserver.config file set, add the following keys: `Proxy ProxyUser ProxyPass ProxyExceptionList` For details, see Setting a proxy connection on the server.	Run the `BESAdmin` command as described in Setting a proxy connection on the server.
or
Set the concatenated key `Proxy = [ProxyUser:ProxyPass@]hostname[:port]` as described in Setting a proxy connection on the server.

Table 2. . Steps to configure communication through a proxy on an IBM Endpoint Manager relay
Relay
Linux and Windows
To communicate with the parent component (relay or server):	To download files from the Internet:
Set the client connection settings that are specified in Setting up a proxy connection on a client or a child relay using the console. Optionally, specify the `ProxyExceptionList` setting to specify local computers or domains that must be reached without using the proxy.	Set `_BESGather_Download_CheckInternetFlag = 1 _BESGather_Download_CheckParentFlag = 0` as described in Setting up a proxy connection on a relay.

Table 3. . Steps to configure communication through a proxy on anIBM Endpoint Manager client
Client
Linux and Windows
Set the client connection settings that are specified in Setting up a proxy connection on a client or a child relay using the console. Optionally, specify the `ProxyExceptionList` setting to specify local computers or domains that must be reached without using the proxy.

Note: The configuration settings that are used in IBM Endpoint Manager version 9.0 Patch 5 or later do not use the BESGatherService, which is deprecated.

The configuration to communicate through a proxy might differ if you upgrade to version 9.0 Patch 5 or later an existing configuration. For example, in version 8.2 the BESGatherService, which is deprecated in version 9.X, was used to configure the communication through a proxy. If you upgrade your IBM Endpoint Manager version 8.2 environment to version 9.0 Patch 5 or later, your proxy configuration continues to use the BESGatherService for backward compatibility. In this case, however, you cannot exploit the new features, for example ProxyExceptionList, until you use the proxy configuration that is supported by the r IBM Endpoint Manager version installed.

Setting a proxy connection on the server

On the IBM Endpoint Manager server 9.0 Patch 5 or later, depending on which platform your sever is installed, you have the following behavior:

On Windows systems:

The BES components that access the internet run, by default, as SYSTEM account on the Windows server.

The proxy configuration is managed in the registry by the key HKEY_LOCAL_MACHINE\SOFTWARE\BigFix\Enterprise Server\Proxy.

Run the following command to create or modify the HKEY_LOCAL_MACHINE\SOFTWARE\BigFix\Enterprise Server\Proxy key in the registry:

BESAdmin /setproxy /proxy:{hostname|IP_Address}[:port] /user:username 
/pass:password [/exceptionlist:exceptionlist]

On Linux systems:

The BES components that access the internet run, by default, as root on the Linux server.

The proxy configuration is defined in the [SOFTWARE\BigFix\Enterprise Server\Proxy] section of the besserver.config file.

These are the values to specify when configuring the communication through a proxy:

Proxy = {hostname|IP_address}[:port]

It is the hostname or IP address and, optionally, the port number of the proxy machine.

ProxyUser = username

It is the username that is used to authenticate with the proxy if the proxy requires authentication.

If you installed your IBM Endpoint Manager server on a Windows system and your proxy requires Kerberos Authentication, use the following syntax ProxyUser = jdoe@example.com replacing jdoe@example.com with your user and domain. The user that you specify must log in to the server and configure its Internet Options to use the proxy.

If you installed your IBM Endpoint Manager server on a Windows system and your proxy requires NTLM Authentication, use the following syntax ProxyUser = jdoe replacing jdoe with the NTLM user. If your proxy requires the domain/realm, the user may need to be specified as jdoe@example.com or as domain/jdoe. The user that you specify must log in to the server and configure its Internet Options to use the proxy.

If you installed your IBM Endpoint Manager server on a Linux system and your proxy requires NTLM Authentication, specify the NTLM user as proxyuser.

On IBM Endpoint Manager on Linux the NTLM authentication does not work if FIPS is enabled.

ProxyPass = password

It is the password that is used to authenticate with the proxy if the proxy requires authentication. The value that is assigned to the password is encrypted in the registry on Windows systems or obfuscated in the configuration file on Linux systems.

ProxyExceptionList = "hostname1, hostname2, IP_Addr_A, IP_Addr_B, domain_Z, domain_Y, ..."

This is an optional setting that you can use to specify computers, domains and subnetworks that must be reached without passing through the proxy.

Each name in this list is matched as either a domain, which contains the hostname, or the hostname itself. For example, example.com would match example.com, example.com:80, and www.example.com, but not www.notanexample.com.

Examples:

ProxyExceptionList = example.com
ProxyExceptionList = example.com,8.168.117.0
ProxyExceptionList = "example.com, 8.168.117.0"

To prevent diverting internal communications towards the proxy agent, specify the following value in the ProxyExceptionList key:

ProxyExceptionList = "localhost, 127.0.0.1"

The setting ProxyExceptionList was introduced in version 9.0.835.0 (Patch 5) for Windows and Linux systems. If you are using IBM Endpoint Manager version 9.0 and you have problems using content that downloads files from the local server, upgrade to IBM Endpoint Manager version 9.0.835.0.

On IBM Endpoint Manager version 8.1, 8.2, and 9.0 for builds earlier than 9.0.835.0, the proxy settings are picked up from the Internet Explorer proxy settings.

Important: Ensure that you restart the BESRootServer component on the server after you create or modify the settings to communicate through a proxy.

Examples:

This example uses a concatenated key notation to specify the proxy settings:

[Software\BigFix\Enterprise Server\Proxy]
  Proxy = [proxyuser:password@]{hostname|IP_address}[:port]

This example defines the communication through a non-authenticating proxy:
```
[Software\BigFix\Enterprise Server\Proxy]
  Proxy = hostname:port
```
This example shows how to exclude from the communication through the proxy:
- The IBM Endpoint Manager client that is installed on the system where you are defining the proxy connection.
- The host with IP address 8.168.117.0.
- The hosts that belong to the domain example.com.
```
[Software\BigFix\Enterprise Server\Proxy]
  Proxy = username:password@hostname
  ProxyExceptionList = "localhost, 127.0.0.1, 8.168.117.0, example.com"
```

For more information about proxy configuration, see Proxy Server Settings.

Setting up a proxy connection on a relay

On the system where the relay is installed, run the following steps to allow the relay to communicate with its parent components:

Open the console and go to Computer section under the All Content domain.
Select the computer where the relay is installed.
Right-click the computer and select Edit Settings.
Select Add to create custom settings.
Enter the Setting Name and Setting Value listed in Table 4.
Click OK to send out the configuration settings, which take effect immediately.

Specify the setting:ProxyExceptionList = "hostname1, hostname2, IP_Addr_A, IP_Addr_B, domain_Z, domain_Y, ..." if the relay must communicate to its parent relays without passing through the proxy. Depending on which platform the relay is installed, add this setting:

On Windows systems:: In the registry in the HKEY_LOCAL_MACHINE\SOFTWARE\BigFix\Enterprise Server\Proxy key.
On Linux systems:: In the besrelay.config file in the [SOFTWARE\BigFix\Enterprise Server\Proxy] section.

Run the following steps if you want to allow your relay to download files through the proxy:

Open the console and go to Computer section under the All Content domain.
Select the computer where the relay is installed.
Right-click the computer and select Edit Settings.

Select Add to create the following custom settings:

_BESGather_Download_CheckInternetFlag = 1
_BESGather_Download_CheckParentFlag = 0

Click OK to send the configuration settings, which take effect immediately.

Note: If the relay is installed on a Linux platform, the configuration file in which the settings are stored is called besrelay.config.

Setting up a proxy connection on a client or a child relay using the console

If a client or a relay must communicate through a proxy with its parent component (relay or server) for Internet requests and for component-to-component communication, set the proxy connection on that system as follows:

Open the console and go to Computer section under the All Content domain.
Select the computer where the client or the child relay is installed.
Right-click the computer and select Edit Settings.
Select Add to create a custom setting.

Enter the Setting Name and Setting Value from the configuration table below:

Table 4. Proxy client configuration settings
Setting Name	Setting Value	Details
`_Enterprise Server _ClientRegister _ProxyServer`	Sets the hostname that is used to reach the proxy.	Default Value: None Setting Type: String Value Range: N/A Task Available: No
`_Enterprise Server _ClientRegister _ProxyPort`	Sets the port that is used by the proxy server.	Default Value: None Setting Type: String Value Range: N/A Task Available: No
`_Enterprise Server _ClientRegister _ProxyUser`	Sets the user name that is used to authenticate with the proxy if the proxy requires authentication.	Default Value: None Setting Type: String Value Range: N/A Task Available: No
`_Enterprise Server _ClientRegister _ProxyPass`	Sets the password that is used to authenticate with the proxy if the proxy requires authentication.	Default Value: None Setting Type: String Value Range: N/A Task Available: No

Click OK to make the setting active.

Depending on which platform the computer is installed, the following settings are stored:

On Windows systems:: In the registry.
On Linux systems:: In the besclient.config file if you configured a client; in the besrelay.config file if you configured a child relay.

All notifications to clients use the UDP protocol, which a standard proxy does not forward. If there is a proxy between the client and a relay, configure upstream communication on the client with the following settings:

Table 5. Proxy client polling configuration settings
Setting Name	Setting Value	Details
`_BESClient_Comm _CommandPollEnable`	Enables the client to poll its parent relay for new actions.	Default Value: 0 (disabled) Setting Type: Boolean Value Range: 1 (enable), 0 (disable) Task Available: Yes
`_BESClient_Comm_ CommandPollInterval Seconds`	Determines how often the client checks with its parent relay for gathering or refresh of content if `_BESClient_Comm_CommandPollEnable` is enabled. To prevent performance degradation avoid specifying settings that are less than 900 seconds.	Default Value: 900 Setting Type: Numeric (seconds) Value Range: 0-4294967295 Task Available: Yes

If you set this configuration, the client queries its relay for new instructions instead of waiting for the UDP ping regarding new actions.

Best practices to consider when defining a proxy connection in version 9.0

Consider the following tips and tricks to avoid common problems:

Starting from version 9.0 the use of the BESGather service is deprecated. However if you use it, ensure that you define the user account exploited by your proxy configuration as follows:
Provision a single user account that has both domain administrator and local administrator rights to the IBM Endpoint Manager server machine.

Reason: The BESRootServer.exe process needs to have local administrator rights to the server machine to properly propagate site content from the database to the server's file system. The BESRootServer.exe needs to have domain administrator rights to negotiate all the LDAP transactions between the console and Active Directory to authenticate users.

Ensure that the user account also has permission to make requests through the proxy to the Internet as a service account.

Reason: The BESRootServer.exe service gathers the site content from public content and site servers.

Ensure that the user has Database Owner (DBO) rights to the BFEnterprise database.

Reason: The user needs to access the BFEnteprise and BESReporting databases as owner with DBO rights.

Use this userid to log in with BES Root Server and BES Gather services.
After you set the communication through the proxy on a Windows server, use the IBM Endpoint Manager Diagnostic Tools to verify that the server, still reported as BESGatherService, can successfully reach the Internet.
Check the GatherDB.log file that is located in the BES Server\GatherDBData folder to verify that the server can gather from the Internet.
Check in the firewall rules if there are any file types that are blocked. In this case, if the content to gather from a site contains at least one file with this file type, then the entire content of that site is not gathered.
Ensure that the password specified in ProxyPass on the server, or in _Enterprise Server_ClientRegister_ProxyPass on the client or relay has not expired.
Make sure that the proxy allows the downloading of arbitrary files from the Internet (for example, it does not block .exe downloads or does not block files with unknown extensions).
Most of files in IBM Endpoint Manager are downloaded from bigfix.com or microsoft.com using HTTP port 80, but it is recommended that you allow the proxy service to download from any location using HTTP, HTTPS, or FTP because there are some downloads that use these protocols.
On Windows systems, verify whether Internet Explorer can reach the Internet using the credentials that are specified in the IBM Endpoint Manager proxy configuration, and test the connectivity with the esync.bigfix.com servers (for example, http://esync.bigfix.com/cgi-bin/bfgather/bessupport).
Make sure that the proxy is bypassed for internal network and component-to-component communications because this might cause problems with how the IBM Endpoint Manager server works and is inefficient for the proxy. Use the ProxyExceptionList setting, if needed, to exclude local systems from the communication through the proxy.
The setting ProxyExceptionList was introduced in IBM Endpoint Manager version 9.0.835.0 for Windows and Linux systems. If you are using IBM Endpoint Manager version 9.0 and you have problems using content that downloads files from the local server, upgrade to IBM Endpoint Manager version 9.0 Patch 5 (9.0.835.0).
By default the HTTP and HTTPS connections time out after 10 seconds, DNS resolution time included. When this happens the HTTP 28 error is logged. In your environment, if the proxy server or the DNS server takes a longer time to establish the TCP connection, you can increase the number of seconds before the connection times out by editing the setting _HTTPRequestSender_Connect_TimeoutSecond. The _HTTPRequestSender_Connect_TimeoutSecond setting affects all the IBM Endpoint Manager, including the Console and the Client, running on the machine for which this setting is set. No other IBM Endpoint Manager component running on other machines in the deployment is affected by the setting. As a best practice, be careful when increasing the value of this setting and try to keep it as low as possible to avoid opening too many sockets concurrently risking socket exhaustion and eventual loss of service.

Feedback