Skip to main content

Link Agent Configuration File

Eva Ferreira
  • Updated

In addition to passing Link Agent configuration options on the command line, you can also run the Link Agent by passing configuration options from a file. Link Agent configuration files are a good option for teams who prefer not to expose API keys in the command line and for teams that want to service multiple Link Tunnels with a single Link Agent.

To pass configuration options from a file, use the --config or -c option, as shown in the following examples:

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

Supported file formats

The supported formats for the configuration file are 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.

At a minimum, the tunnels section should include the Link Agent API name and API key. See the following examples for commonly used configuration options:

JSON:

{
    "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"
        }
    ]
}

YAML:


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
Combining multiple tunnels can impact performance and stability

Combining multiple tunnels in the same Agent instance can reduce the number of unique agent instances you need to manage. This is a useful option if you have several low-volume tunnels, but you should use caution with this approach because increasing the amount of traffic handled by the same Link Agent may increase its memory and/or CPU requirements. 

If you combine multiple tunnels into the same Link Agent instance, we recommend the following approach:

  • Understand the baseline 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, monitor the host while tests are active on all managed tunnels. 
  • If necessary, 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, you can add those PAC settings to your Link Agent configuration file. When adding PAC settings to the config file, make sure you do not also have static proxy settings configured. The httpProxy, proxyAuth, and proxyExclusions settings must be removed before adding the proxyAutoConfiguration setting.

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.

 The following JSON and YAML examples show how to configure the Link Agent to use Proxy Auto-Configuration (PAC):

JSON:

{
  "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"
  },
}

YAML: 

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

At a minimum, the PAC must include a 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, for example: file:///opt/mabl/link-agent/pac.js.

Additional settings include:

  • auth: If any of your proxy servers require authentication, 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, for example: proxy.example.com:8080.
  • reloadPeriodMinutes: this 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.

Related articles