Using mabl Link

Customers use mabl Link to establish a secure tunnel between their private network and the mabl cloud so that they can run tests in the mabl cloud against internal environments such as staging and localhost.

📘

Note

Mabl link works best when run on a persistent server or VM on your network.

Step 1: Retrieve the API key for your workspace

In order to use the mabl Link agent, you will need a mabl API key. To obtain a copy of your API key, which is specific to a workspace, navigate to Settings => APIs in the mabl app, and create a new key of type Link Agent if one does not already exist.

Step 2: Download and install the Link Agent

The Link Agent is a small Java-based application that is responsible for creating the secure tunnel to the mabl cloud. It can be installed using Docker or a Java-based distribution package. We recommend using Docker, if you can, since it is the simplest to setup and maintain. To obtain your preferred distribution, navigate to Settings ⇒ Networking in the mabl app.

Step 3: Run the Link Agent

If using Docker or setting up the agent on Windows, please refer to the respective Docker or Windows instructions and skip this step.

📘

Link Agent system requirements

Link Agent requires a JVM that supports Java 9 or later and there are no other dependencies. Link Agent has been tested with both the OpenJDK and Hotspot JVMs. We recommend the OpenJDK 11 for Linux, Windows, and MacOS.

We recommend that the machine/VM running the Link Agent has at least:

• 1 vCPU
• 4GB RAM
• 2GB storage

When running in the cloud, we recommend avoiding burstable instance types which may experience periods of significantly reduced CPU and network performance. We recommend the following instance classes:

• AWS: C class instances
• GCP: N2, N2D, T2D, C2, C2D class instances

🚧

If you see this error: Unrecognized option: --add-opens

If you see an error message similar to the following when starting the agent, it means that your version of Java is too old, or the correct version is not on your path:

Unrecognized option: --add-opens
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

If you are planning on using the Java-based archive for the link agent, you can download it from your mabl workspace under Settings > Networking.

Once you download the Java-based archive for the Link Agent, please copy it to a machine that has access to the application environment (host) that you would like to run tests against, and then extract the file archive to a convenient location. This can be your personal computer, if you are just experimenting.

# Extract bzip2 tar:
tar xjf link-agent.tbz2

# Or extract zip:
unzip link-agent.zip

In a terminal, enter the link agent directory that was extracted from the archive, and then execute the Link Agent. The Link Agent requires two parameters to be passed on the command-line:

• --api-key <your-api-key>
• --name <valid-agent-name>

The API key is the key that you copied in Step 1 above. The name is an identifier of your choice that you will use later to identify this agent. The name must consist only of lowercase letters, numbers, and hyphens, and it cannot be longer than 24 characters in length. Expressed as a regular expression, the name must conform to ^[a-z0-9-]{1,24}$ .

The agent will connect to a generated DNS name of the form <host>.link.mabl.com where the <host> component is generated based on the --name argument passed at startup and will never change as long as the agent is started using the same name. IT security teams can allowlist/permitlist that individual FQDN or the wildcard *.link.mabl.com.

An example of a valid Link Agent start-up command is:

cd link-agent

# Start the Link Agent as a foreground process
bin/link-agent --api-key fake-api-key --name qa-env-01

# Or you may wish to start the Link Agent in the background
# and keep it running even after you log out:
nohup bin/link-agent --api-key fake-api-key --name qa-env-01 &

cd link-agent

# NOTE: requires using the Java JDK (not JRE)

# Start the Link Agent as a foreground process
bin/link-agent --api-key fake-api-key --name qa-env-01

# Or you may wish to start the Link Agent in the background
# and keep it running even after you log out:
nohup bin/link-agent --api-key fake-api-key --name qa-env-01 &

cd link-agent

# Start the Link Agent as a foreground process
bin\link-agent.bat --api-key fake-api-key --name qa-env-01

📘

Alternative configuration method: configuration file

As an alternative to passing configuration options on the command line, you may also configure the Link Agent via a configuration file. The configuration file option may be preferred to avoid displaying the API key when listing processes and to keep the key out of your shell history. Additionally, if you are managing multiple Link Agents, the config file may allow you to standardize your start-up script such that only the config file needs to change for each Link Agent instance that is deployed.

For more information about using the configuration file see the Link Agent Configuration File documentation.

Support for HTTP forward proxies

The Link Agent can be configured to use an HTTP forward proxy, including support for basic proxy auth. Traffic will be routed through that proxy according to the selected proxy mode and exclusions. Use the following command-line arguments to configure the proxy:

• --http-proxy <host>:<port> (or -h <host>:<port>)
• --proxy-auth <username>:<password> (or -i <username>:<password>)
• --proxy-mode <all|none|mabl|upstream> (or -y <all|none|mabl|upstream>)
• --proxy-exclude <exclusions>

📘

Proxy mode options

The --proxy-mode (or -y) flag allows you to specify which connections will be made via the configured proxy. If not specified the default mode is mabl. The modes that can be specified are:

• all : All connections will be made through the configured proxy.
• none : No connections will be made through the configured proxy (all will be made without using any proxy).
• mabl : Only connections to mabl (API calls and the secure tunnel itself) will be made through the configured proxy; all other connections (e.g. to the system under test) will be made without using any proxy. This is the default setting.
• upstream : Only connections to upstream hosts (e.g. the system under test) will be made through the configured proxy; connections to mabl will be made without using any proxy.

📘

Proxy exclusions

Proxy exclusions can be used when a proxy is required to access certain hosts but not others. Exclusions are specified as a comma-delimited list of expressions. An exclusion expression can be a single IP address, a CIDR range, or a host/domain. When a host/domain is specified, it is treated as a suffix. For example, if your use example.com in an exclusion, that exclusion will also match www.example.com, api.example.com, and host1.subdomain1.example.com. Examples of each type of exclusion are listed below:

• Single IP address: 192.168.10.50
• CIDR range: 10.0.0.0/8
• Host/domain: example.com

A complete example might look like this:

--proxy-exclude "localhost,127.0.0.1,192.168.10.50,10.0.0.0/8,example.com"

Checking the status of the Link Agent process

You may need to know whether the Link Agent is running and what its current status is for the purposes of a health check or integrating with automation. The Link Agent writes two files under the run directory which may be helpful in these cases:

• link-agent.pid contains the process ID of the Link Agent and will only exist if the agent is running
• status contains the current status of the Link Agent and will only exist if the agent is running. When the agent is fully connected and ready to accept test traffic the contents of this file will be the string ready.

Step 4: Validate the Link connection is live

After starting the Link Agent (see Step 3 above), return to the mabl UI and navigate to Settings ⇒ Networking. Under the mabl Link Agents heading you should see an entry with the agent you just started. Initially you should see a message indicating that the tunnel is initializing, similar to this:

Within the next couple of minutes the Link Agent should become Connected and show state Ready within a couple of minutes of starting it up.

📘

Troubleshooting agent connectivity Issues

If you do not see any agents listed, verify that the agent process is still running on the host where you started it, and check the log file (logs/agent.log) for errors. If you are having trouble getting the agent to start, contact mabl support via the in-app chat or at [email protected]

If you do see an agent listed, but it is not connected, first confirm that the name matches the name you specified when starting the agent. If the agent is not connected, wait a few minutes and see if the connection becomes established. It can sometimes take a few minutes to fully connect, especially the first time you start a new Link agent. If the agent does not connect after 10 minutes, contact mabl support.

Allowlisting mabl Link

If your company has strict firewall rules, your IT team only needs to allowlist (or permitlist) the outbound (egress) traffic on port 443 to just two endpoints:

• api.mabl.com
• <host>.link.mabl.com

The Link Agent will only initiate outbound (egress) connections to the two endpoints above. The DNS name (<host>.link.mabl.com ) that the agent connects to will always resolve to the same static IP address, so you can allowlist just the IP address if you prefer not to allowlist the DNS name.

If you plan to have many agents with different names, you should consider allowlisting the wildcard domain *.link.mabl.com to account for the different fully qualified domain names (FQDNs) that each agent with a different name will have.

Step 5: Configure a mabl environment to use the Link Agent

Navigate to Configuration ⇒ Environments in the mabl UI, and either create a new environment or edit an existing environment. You can disable/enable the agent by toggling the Use link agent checkbox. Note that the agent must be started before it can appear in this configuration drop-down menu

🚧

Associating a Link Agent with an existing environment

When you associate a Link Agent with an environment, all plans associated with that environment will have their traffic routed through the selected Link Agent. It is usually a better idea to create a new dedicated environment for a Link Agent so that existing plans are not affected. One exception to this general rule is when all of your environments are private, and none of your plans can run successfully until a Link Agent has been configured.

Step 6: Associate the link-enabled environment with a plan

In order to route traffic through the Link Agent, the environment you created in Step 5 must be associated with a plan. Either create a new plan or edit an existing plan in the mabl UI, and select the environment you created in Step 5.

📘

URL is resolved by the Link Agent

The URL you enter will be resolved by the Link Agent (not within mabl's network) so you can use any URL that the host on which the Link Agent is running can resolve. This URL can include non-public FQDNs, private IP addresses, and /etc/hosts entries such as https://app-local.example.com.

Step 7: Run the test plan over Link

Now run the plan you created in the prior step. When you view the test run results for that plan you should see messages indicating that mabl searches for and finds an active Link Agent, similar to the message below:

When the Link Agent is not started or has not finished connecting before the test run started, you may see an error like the one below:

Overriding the Link Agent name in a Deployment Event

In some scenarios, such as when a developer needs to test against a local development environment, it may be necessary to temporarily override the Link Agent that is used for some tests/plans. It is possible to dynamically override the configured Link Agent by passing a new Link Agent name in a deployment event (see Triggering tests via API). To override the Link Agent used in a deployment event, add the following parameter to the JSON request body:

"plan_overrides":{"link_agent_label":"your-agent-name-here"}