Link Agent Configuration File

In addition to passing Link Agent configuration options on the command line, you can also pass in Link Agent configuration options from a file. Link Agent configuration files are a good option if you prefer not to expose API keys in the command line or you want to service multiple Link Tunnels with a single Link Agent

This article outlines the available options for using a Link Agent configuration file:

• Basic setup
• Optional settings
• Sample templates

Basic setup

The Link Agent configuration file may be in JSON or YAML format. At a minimum, the tunnels section should include the following:

• apiKey - a “Link Agent” API key created in the mabl app: Settings > APIs
• name - a Link Agent name between 1 and 24 characters long that consists of lowercase letters, numbers, and dashes. Expressed as a regular expression, the name must conform to ^[a-z0-9-]{1,24}$.

{
   "tunnels": [
       {
           "apiKey": "apiKey1",
           "name": "name1"
       }
   ]
}

tunnels:
  - apiKey: my-api-key-1
    name: my-tunnel-name-1

For more details on how to customize the Link Agent configuration file, including servicing multiple Link Tunnels or adding proxy settings and connection filters, check out the following section on optional settings.

To start up the Link Agent with a configuration 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

To keep the Link Tunnel active during future updates to the configuration file, pass the -R or --config-reload command-line option when starting the Link Agent. For example:

bin/link-agent --config /path/to/config.json -R
# or:
bin/link-agent -c /path/to/config.yaml --config-reload

When the auto-reload setting is used in conjunction with a Link Agent configuration file, the Agent automatically monitors that file for changes and applies them when detected

Optional settings

You can further customize the Link Agent configuration file to accommodate the following setups and requirements:

• Servicing multiple Link Tunnels
• Static proxy settings
• Proxy Auto Configuration (PAC) files
• Connection filters
• Disabling auto-updates

Servicing multiple Link Tunnels

By combining multiple tunnels in a single configuration file, you can reduce the number of unique Link Agent instances you need to manage. This option is useful if you have several low-volume tunnels.

For each additional Link Tunnel that you want to service, add another entry with apiKey and name to the tunnels section of the configuration file.

• Tunnels that are associated with the same mabl workspace may use the same "Link Agent" API key.
• Tunnels that are associated with different mabl workspaces should use the "Link Agent" API key from their respective workspace.

The following JSON and YAML examples show a configuration file that services two Link Tunnels:

{
   "tunnels": [
       {
           "apiKey": "apiKey1",
           "name": "name1"
       },
       {
            "apiKey": "apiKey2",
            "name": "name2"
        }
    ]
}

tunnels:
  - apiKey: my-api-key-1
    name: my-tunnel-name-1
  - apiKey: my-api-key-2
    name: my-tunnel-name-2

Static proxy settings

If your network uses a forward proxy, you can include proxy settings to ensure outgoing Link traffic is successfully routed to the mabl Link Service:

• httpProxy - (required) the proxy server host that you’re connecting to
• proxyAuth - if the proxy server requires authentication, provide the username and password
• proxyMode - specify which traffic should use the proxy. The default is mabl
• proxyExclusions - configure outgoing mabl Link traffic to bypass specific IP addresses, CIDR ranges, hosts, or domains.

See the article on forward proxies for mabl Link traffic for more details on these properties.

The following JSON and YAML examples show how to incorporate static proxy settings into the Link Agent configuration file:

{
   "httpProxy": {
       "host": "host",
       "port": 1234
   },
   "proxyAuth": {
       "password": "password",
       "username": "username"
   },
   "proxyExclusions": [
       "localhost",
       "127.0.0.1"
   ],
   "proxyMode": "all"
}

httpProxy:
  host: host
  port: 1234
proxyAuth:
  password: my-proxy-password
  username: my-proxy-username
proxyExclusions:
  - localhost
  - 127.0.0.1
proxyMode: all

Proxy Auto Configuration (PAC) files

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.

At a minimum, the PAC must include a URL. PAC file settings include the following:

• 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](http://pac.js).
• 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.

The following JSON and YAML examples show how to incorporate PAC settings into the the Link Agent configuration file:

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

Connection filters

With connection filters, you can restrict the hosts that your Link Agent is allowed to connect to. Connection filters are recommended only when absolutely necessary, such as to satisfy mandatory security or compliance requirements. If a connection filter blocks connections to dependent resources in the application under test, it could result in errors in mabl test runs.

Connection filters require two settings: mode and destination.

The three possible connection modes are:

• allow: The Link Agent is allowed to connect only to targets matching the filter
• deny: The Link Agent is allowed to connect to any target except those matching the filter
• disabled: The connection filter is disabled. This option is mainly for debugging purposes to allow turning on/off the filter without removing the configuration

Destinations represent the target for the connection filter. They may be specified using a host expression, a port, or both using one of the following forms:

• Host only: [host-expression]
• Port only :[port]
• Host and port: [host-expression]:[port]

The following JSON and YAML examples show how to incorporate connection filters into the the Link Agent configuration file:

{
  "connectionFilter": {
    "mode": "deny",
    "destinations": [
      "example.com",
      "10.0.0.0/8:22",
      "127.0.0.1",
      ":80"
    ]
  }
}

connectionFilter:
  mode: deny
  destinations:
  - example.com
  - 10.0.0.0/8:22
  - 127.0.0.1
  - :80

A host destination can be specified using a single IP address, CIDR block, or FQDN suffix. The following table lists examples of supported host expressions:

Disabling auto-updates

The mabl Link Agent automatically updates to ensure it always runs with the latest additions, changes, and fixes. To disable auto-updates, add the disableAutoUpdates setting and set it to true.

{
   "disableAutoUpdates": true
}

disableAutoUpdates: true

Sample templates

As you set up your own Link Agent configuration file, you can use the following comprehensive template as a guide. You can also check the config directory in the Link Agent distribution for example configuration files: config.example.json and config.example.yaml.

{
   "disableAutoUpdates": false,
   "httpProxy": {
       "host": "host",
       "port": 1234
   },
   "proxyAuth": {
       "password": "password",
       "username": "username"
   },
   "proxyExclusions": [
       "localhost",
       "127.0.0.1"
   ],
   "proxyMode": "all",
   "connectionFilter": {
       "mode": "deny",
       "destinations": [
           "example.com",
           "10.0.0.0/8:22",
           "127.0.0.1",
           ":80"
        ]
   },
   "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
connectionFilter:
  mode: deny
  destinations:
  - example.com
  - 10.0.0.0/8:22
  - 127.0.0.1
  - :80
tunnels:
  - apiKey: my-api-key-1
    name: my-tunnel-name-1
  - apiKey: my-api-key-2
    name: my-tunnel-name-2