Link Agent configuration file

In addition to passing Link Agent options on the command line, you can keep them in a configuration file. A configuration file keeps API keys off the command line, lets one Link Agent serve several tunnels, and lets you change tunnels and settings while the agent runs.

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

• Basic setup
• Changing the configuration while the agent runs
• Optional settings
• Sample templates

Basic setup

The Link Agent configuration file may be in JSON or YAML format. The agent reads the format from the file extension: a file ending in .yaml or .yml is read as YAML, and any other file, including one ending in .json, is read as JSON. At a minimum, the tunnels section should include the following for each tunnel:

• apiKey - a "Link Agent" API key created in the mabl app: Settings > APIs
• name - a tunnel 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": "{your-api-key}",
           "name": "qa-env-01"
       }
   ]
}

tunnels:
  - apiKey: {your-api-key}
    name: qa-env-01

To start the Link Agent with a configuration file, use the --config or -c option:

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

The Link Agent checks the API keys and tunnel names when it starts, and reports one it can't use instead of retrying it indefinitely. A file copied from an example and left with placeholder values is the most common cause.

Changing the configuration while the agent runs

A Link Agent started with a configuration file watches the file and applies your changes while it runs, so you don't need to restart it:

• A tunnel you add connects right away.
• A tunnel you remove stops taking new connections and lets its current ones finish, so tests already running through it aren't interrupted. It then waits until you shut down the agent or remove the tunnel in the mabl app.
• Proxy settings, connection filters, and the log level apply to the running tunnels.

If a changed file can't be read or has an invalid setting, the Link Agent logs the problem and keeps running with its previous configuration.

Watching is on by default. To turn it off, start the agent with --no-config-reload. The -R and --config-reload options are still accepted, but are no longer needed.

Optional settings

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

• Servicing multiple Link tunnels
• Point of contact
• Static proxy settings
• Proxy auto-configuration (PAC) files
• Connection filters
• Disabling auto-updates
• Shutdown drain timeout
• Deprecated settings

Servicing multiple Link tunnels

By combining multiple tunnels in a single configuration file, you can reduce the number of Link Agents you need to manage. For each additional tunnel, add another entry with apiKey and name to the tunnels section:

• Tunnels that belong to the same mabl workspace may use the same "Link Agent" API key.
• Tunnels that belong to different workspaces use the "Link Agent" API key from their respective workspace.
• A company tunnel uses a company "Link Agent" API key. A company tunnel and a workspace tunnel may even share a name, which is how you move a workspace tunnel to your company without editing any environments.

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

{
   "tunnels": [
       {
           "apiKey": "{your-api-key-1}",
           "name": "qa-env-01"
       },
       {
           "apiKey": "{your-api-key-2}",
           "name": "staging-01"
       }
   ]
}

tunnels:
  - apiKey: {your-api-key-1}
    name: qa-env-01
  - apiKey: {your-api-key-2}
    name: staging-01

Each tunnel adds to the memory and CPU the Link Agent host needs. Before you combine several busy tunnels on one agent, see Sizing and scaling Link Agents.

Point of contact

Set pointOfContact to the person or team in your organization who maintains the Link Agent, such as an email address or a team name. It appears in the agent's details on Settings > Networking, so anyone who sees a problem with the agent knows whom to contact.

{
   "pointOfContact": "qa-platform-team@example.com"
}

pointOfContact: qa-platform-team@example.com

Static proxy settings

If your network uses a forward proxy, include proxy settings so that outgoing Link traffic reaches mabl:

• httpProxy - (required) the proxy server host and port
• proxyAuth - if the proxy server requires authentication, the username and password
• proxyMode - which traffic should use the proxy: mabl, all, upstream, none, or auto
• proxyExclusions - IP addresses, CIDR ranges, hosts, or domains that outgoing Link traffic reaches directly

If the configuration file has no proxy settings at all, the Link Agent follows the proxy configuration of its host operating system, including a PAC script if one is configured. To connect directly even though the host has a proxy configured, set proxyMode to none.

See Forward proxies for mabl Link traffic for more details on these properties.

The following JSON and YAML examples show how to include static proxy settings in the configuration file:

{
   "httpProxy": {
       "host": "proxy.example.com",
       "port": 8080
   },
   "proxyAuth": {
       "password": "{proxy-password}",
       "username": "{proxy-username}"
   },
   "proxyExclusions": [
       "localhost",
       "127.0.0.1"
   ],
   "proxyMode": "all"
}

httpProxy:
  host: proxy.example.com
  port: 8080
proxyAuth:
  password: {proxy-password}
  username: {proxy-username}
proxyExclusions:
  - localhost
  - 127.0.0.1
proxyMode: all

Proxy auto-configuration (PAC) files

If your organization uses a PAC file to configure proxy settings, add the PAC settings to the configuration file. Don't combine them with static proxy settings: remove httpProxy and proxyExclusions before adding proxyAutoConfiguration.

At a minimum, the PAC settings must include a URL:

• url - usually an http:// URL. To load a PAC script from the local filesystem instead, use a file:// URL, for example: file:///opt/mabl/link-agent/pac.js.
• auth - if any of your proxy servers require authentication, a separate entry for each of them. Name each proxy exactly as the PAC script returns it, including both the host name and port, for example: proxy.example.com:8080.
• reloadPeriodMinutes - how often the Link Agent reloads the PAC. To keep connections fast, the agent doesn't reload the PAC on every connection. It reloads it in the background instead, once a minute by default.

The following JSON and YAML examples show how to include PAC settings in the configuration file:

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

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

Connection filters

With connection filters, you can restrict the hosts your Link Agent is allowed to connect to. Use connection filters only when necessary, such as to satisfy mandatory security or compliance requirements. If a connection filter blocks connections to resources your application depends on, mabl test runs can fail.

Connection filters require two settings: mode and destinations.

The three possible 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, to turn the filter off and on without removing its configuration

Destinations represent the target for the connection filter. They may be specified using a host expression, a port, or both, in 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 include connection filters in the configuration file:

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

connectionFilter:
  mode: deny
  destinations:
  - example.com
  - 10.0.0.0/8:22
  - 127.0.0.1
  - "[2001:db8::1]:443"
  - :80

A host destination can be a single IP address, a CIDR block, or an FQDN suffix. IPv6 addresses and CIDR blocks are supported too. To add a port to an IPv6 address, put the address in square brackets. The following table lists examples of supported host expressions:

Disabling auto-updates

The Link Agent checks for a new version each time it starts. If one is available, the agent installs it and restarts into it before it connects any tunnels. A running agent doesn't check again, even when it reconnects after a network interruption, so an agent that runs for a long time only picks up a new version when it next starts, for example when you restart its service or its host. To install the latest version without waiting, see Install an update now.

The Link Agent that mabl link-agents start runs is part of the mabl CLI and doesn't update itself. To update it, install a newer version of the mabl CLI.

To turn off automatic updates, set disableAutoUpdates to true. See Maintaining and updating Link Agents for how to install updates yourself.

{
   "disableAutoUpdates": true
}

disableAutoUpdates: true

Shutdown drain timeout

When the Link Agent stops, it lets in-flight connections finish first. Set shutdownDrainTimeoutSeconds to limit how long it waits for them, in seconds.

Deprecated settings

The connections and maxConnectionAttempts settings only apply to the legacy Link protocol. Link 3.0 ignores them, the Link Agent logs a notice when they are set, and a future release will remove them. Remove them from your configuration file. See Migrating from legacy Link to Link 3.0.

Sample templates

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

{
   "pointOfContact": "qa-platform-team@example.com",
   "disableAutoUpdates": false,
   "httpProxy": {
       "host": "proxy.example.com",
       "port": 8080
   },
   "proxyAuth": {
       "password": "{proxy-password}",
       "username": "{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": "{your-api-key-1}",
           "name": "qa-env-01"
       },
       {
           "apiKey": "{your-api-key-2}",
           "name": "staging-01"
       }
   ]
}

pointOfContact: qa-platform-team@example.com
disableAutoUpdates: false
httpProxy:
  host: proxy.example.com
  port: 8080
proxyAuth:
  password: {proxy-password}
  username: {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: {your-api-key-1}
    name: qa-env-01
  - apiKey: {your-api-key-2}
    name: staging-01