Link Agent Configuration File

Using the Link Agent configuration file

In addition to passing configuration options on the command line, the Link Agent can also accept a configuration file. To pass configuration options from a file, use one of the following command-line arguments:

--config /path/to/config.json
# Or:
-c /path/to/config.yaml

There are two supported formats for the configuration file: JSON and YAML. Examples of each can be found inside the config directory of the Link Agent distribution in the files config.example.json and config.example.yaml. Here are examples of all commonly used configuration options:

{
  "disableAutoUpdates": false,
  "httpProxy": {
    "host": "host",
    "port": 1234
  },
  "proxyAuth": {
    "password": "password",
    "username": "username"
  },
  "proxyExclusions": [
    "localhost",
    "127.0.0.1"
  ],
  "proxyMode": "all",
  "tunnels": [
    {
      "apiKey": "apiKey1",
      "name": "name1"
    },
    {
      "apiKey": "apiKey2",
      "name": "name2"
    }
  ]
}

disableAutoUpdates: false
httpProxy:
  host: host
  port: 1234
maxConnectionAttempts: 1
proxyAuth:
  password: my-proxy-password
  username: my-proxy-username
proxyExclusions:
  - localhost
  - 127.0.0.1
proxyMode: all
tunnels:
  - apiKey: my-api-key-1
    name: my-tunnel-name-1
  - apiKey: my-api-key-2
    name: my-tunnel-name-2

Configuring the Link Agent to manage multiple tunnels

Note that it is possible to define multiple tunnels in the same configuration file. If you do so, the same Link Agent instance will be used to establish every tunnel specified in the configuration. Combining multiple tunnels in the same Agent can reduce the number of unique agent instances you need to manage and is particularly useful if you have several low-volume tunnels. Please see the note below about using caution when combining multiple tunnels into the same Link Agent.

🚧

Combining multiple tunnels may impact performance and stability

Use caution when combining multiple tunnels in the same Link Agent instance. Increasing the amount of traffic handled by the same Link Agent may increase its memory and/or CPU requirements. Before combining multiple tunnels into the same Link Agent it is recommended to first know the baseline resource usage for the host where the Link Agent is running. Add tunnels one at a time. After adding each tunnel, monitor the agent log for errors and observe how the memory and CPU usage on the host change relative to the baseline. For accurate measurements it is important to monitor the host while tests are active on all managed tunnels. Observe average and peak resource utilization, and increase the host's memory and CPU resources as necessary. It may also be necessary to increase the memory available to the JVM.

Configuring the Link Agent to use Proxy Auto-Configuration (PAC)

If your organization uses a PAC file/script to configure proxy settings, the Link Agent can be configured to use that PAC. Below are example JSON and YAML config snippets showing how to do so:

{
  "proxyAutoConfiguration": {
    "auth": {
      "proxy1.example.com:8080": {
        "username": "my-user-1",
        "password": "password-1"
      },
      "proxy2.example.com:8080": {
        "username": "my-user-2",
        "password": "password-2"
      }
    },
    "reloadPeriodMinutes": 5,
    "url": "http://proxy.example.com/pac.js"
  },
}

proxyAutoConfiguration:
  auth:
    proxy1.example.com:8080:
      username: my-user-1
      password: my-password-1
    proxy2.example.com:8080:
      username: my-user-2
      password: my-password-2
  reloadPeriodMinutes: 5
  url: http://proxy.example.com/pac.js

The only required setting for the PAC is the URL. Usually this is an http:// URL. If you want to load a PAC script from a file on the local filesystem instead, a file:// URL may be used, e.g. file:///opt/mabl/link-agent/pac.js.

If any of your proxy servers require authentication, you must include a separate auth entry for each proxy that requires authentication. The proxy for each credential setting should be specified exactly as it is returned by the PAC script, including both the hostname and port e.g. proxy.example.com:8080.

The optional reloadPeriodMinutes setting determines how often the Link Agent will reload the PAC. To minimize connection latency the Link Agent does not reload the PAC on every connection attempt. Instead, it periodically reloads the PAC in the background. In most cases the PAC does not change frequently, so it should be safe to only perform this reload every few minutes. The default setting is to reload the PAC once per minute.

🚧

Static proxy and PAC settings are mutually exclusive

If you add PAC settings to your config file, ensure that you do not also have static proxy settings configured. The httpProxy, proxyAuth, and proxyExclusions settings must be removed before adding proxyAutoConfiguration.

📘

Proxy mode is ignored when PAC is configured

When the Link Agent is configured to use a PAC, the proxyMode setting is ignored because the PAC script determines which URLs should use a proxy and which should make direct connections.