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. To setup mabl Link, please watch this quick-setup video and follow the steps below.

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.

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.

Do not use the OpenJ9 variant of Java as this has been known to cause problems for some customers.

Even though there are no strict minimum requirements, we recommend that the machine has at least 1 vCPU, 1GB RAM and 2GB storage.

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 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 whitelist 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

Support for HTTP forward proxies

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

  • --http-proxy <host>:<port>
  • --proxy-auth <username>:<password>

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 support@mabl.com.

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.

Whitelisting mabl Link

If your company has strict firewall rules, your IT team only needs to whitelist the outbound (egress) traffic on port 433 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 whitelist just the IP address if you prefer not to whitelist the DNS name.

If you plan to have many agents with different names, you should consider whitelisting 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 journey 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:


Using mabl Link


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.