Configuring CIC Agent to work with a Proxy

To configure a proxy to work with CIC Agent, you use the command-line interface to the CIC Agent service from either Linux or Windows as follows:

Linux

cleo-agent-downloader [-p=<JSON>] [-c=<CERT>] [-d] COMMAND [arg...]

Windows

cleo-agent-downloader.exe [-p <JSON>] [-c <CERT>] [-d] COMMAND [arg...]

The cleo-agent-downloader client only supports installations in the default platform locations for $AGENT_HOME.

Linux: /opt/cleo/agent

Windows: C:\Program Files\Cleo\Agent

Command options

Use the following global options and commands for the CIC Agent CLI:

Global Options

Commands

Configuration File

Use the proxy.json file to specify proxy configuration values.

The Agent reloads the file $AGENT_HOME/conf/proxy.json whenever it is changed. For short-lived connections, such as REST calls, SQS, S3, this works since the new proxy settings will get applied on the next connection attempt. However, for long-lived connections, like IoT, the connection might not pick up the new settings as often as they change. In this case, restart the Agent to pick up changes to the proxy.json file. 

The format of the proxy.json file is as follows:

  {
      "discoveryMethod": "USE_NETWORK_SETTINGS",
      "configurationUrl": "",
      "proxyHost": "",
      "proxyPort": 0,
      "proxyType": "HTTP",
      "proxyWhiteList": "",
      "proxyUser": "",
      "proxyPassword": ""
  }

Authenticated Proxies

If the proxy requires authentication, the proxyUser and proxyPassword fields should be set. The Agent will encrypt the password and rewrite the proxy.json file including the encrypted value.

Whitelist

If there are certain addresses that should not be proxied, add them to the proxyWhiteList field.

Certificates

If the proxy is using its own self-signed SSL certificate, add it to the $AGENT_HOME/data/certs directory and the Agent will trust it in addition to the standard set of certificates present in the Java cacerts file. The Agent supports PEM, DER and PKCS#7 formats. The certificates are loaded when the Agent starts up.

The certificates in $AGENT_HOME/data/certs are loaded when the agent starts up, except in the case where the Agent is not activated yet. In that case, the files are loaded immediately before the first connection attempt is made to the cloud. This enables the cleo-agent client to copy the file to the Agent immediately after the installation completes but before beginning the activation sequence.

Agent Client

The cleo-agent client also supports proxied environments, either by supplying a proxy.json file or by using the default file present in $AGENT_HOME/conf/proxy.json if the Agent is already installed.

On Windows systems, the client automatically detects any IE proxy settings in effect for the user running the client.

If the -p option was specified, proxy settings are written to the $AGENT_HOME/conf/proxy.json file as part of the activate command. In addition, if a certificate was provided on the command line, it is copied into the $AGENT_HOME/data/certs directory.