Use the Linux and macOS installer, install.sh, to install the mabl Link Agent as a service that starts when the host boots and restarts if it stops. The installer asks for your tunnels and your proxy as it runs, writes them to a configuration file, and can start the agent when it finishes. Every question is also a command-line option, so you can run the same installer unattended.
Before you start
- A "Link Agent" API key and a tunnel name. See Link Agent setup.
- Java 11 or later on the host. The installer uses the Java it finds through
JAVA_HOMEor thePATH, or the one you name with--java. - A host that uses systemd (most Linux distributions) or macOS, and that meets the Link Agent requirements.
- Administrator access (
sudo) to register the service.
Install the Link Agent
-
Download the tar.bz2 or zip archive from Settings > Networking and copy it to the host.
-
Extract the archive and open the extracted directory:
tar xjf link-agent.tbz2 cd link-agent -
Run the installer:
sudo ./install.sh -
Answer the installer's questions: the tunnels to serve, each with its tunnel name and API key, and, if you have one, how the agent should reach mabl through your proxy.
-
When the installer offers to raise the host's socket-buffer limits, accept. mabl recommends this tuning on every host. See Raise the host's socket-buffer limits.
When it finishes, the installer starts the Link Agent and prints where it installed everything. By default:
| Item | Location |
|---|---|
| Link Agent | /opt/mabl/link-agent |
| Configuration file | /opt/mabl/link-agent/config/config.yaml |
| Log | /opt/mabl/link-agent/logs/agent.log |
| Service account |
mabl, a system account the installer creates |
Confirm that the agent shows Connected on Settings > Networking, as described in Link Agent setup.
Install without prompts
To install without questions, for example from a provisioning script, pass the answers as options and add --yes:
sudo ./install.sh --yes --tunnel qa-env-01={your-api-key} --proxy none
Repeat --tunnel to serve more than one tunnel. The main options are:
| Option | Description |
|---|---|
--tunnel {name}={api-key} |
A tunnel to serve. Repeat for more. Replaces the tunnels in the configuration file. |
--proxy {choice} |
How the agent reaches mabl: auto follows the host's proxy settings, manual uses a proxy you name, pac uses a proxy auto-configuration script, none connects directly, and keep (the default) leaves the configuration file's proxy settings as they are. |
--proxy-host {host}, --proxy-port {port}
|
The proxy to use with --proxy manual. |
--proxy-mode {mode} |
With --proxy manual, which traffic uses the proxy: mabl (the default), all, or upstream. See Forward proxies for mabl Link traffic. |
--pac-url {url} |
The PAC script to use with --proxy pac. |
--proxy-user {name}, --proxy-password {password}
|
Credentials, if the proxy needs them. |
--proxy-exclude {list} |
With --proxy manual, a comma-separated list of destinations to reach directly. |
--prefix {directory} |
Where to install the Link Agent. The default is /opt/mabl/link-agent. |
--user {name} |
The account that owns the installation and runs the service. The default is mabl, created as a system account if it doesn't exist. |
--java {path} |
The Java to run the Link Agent with. |
--tune, --no-tune
|
Raise, or don't raise, the host's socket-buffer limits. The installer raises them by default when it runs as root. |
--service, --no-service
|
Register, or don't register, the service that starts the agent at boot. |
--start, --no-start
|
Start, or don't start, the service when the installation finishes. By default, it starts when the configuration names at least one tunnel. |
--yes, -y
|
Take the default for every question and never prompt. |
Run ./install.sh --help for every option. To see the service definition the installer would write, without installing anything, run ./install.sh --print-unit.
Secrets on the command line
While the installer runs, its options are visible to other users on the host through tools like ps, including API keys in --tunnel and a password in --proxy-password. On a shared host, let the installer prompt for secrets instead, or put them in the configuration file afterwards. The configuration file the installer writes is readable only by the service account.
Manage the service
The installer registers the Link Agent with the host's service manager:
The service is named mabl-link-agent.
# Check the service
systemctl status mabl-link-agent
# Follow the service's output
journalctl -u mabl-link-agent -f
# Start, stop, or restart the service
sudo systemctl start mabl-link-agent
sudo systemctl stop mabl-link-agent
sudo systemctl restart mabl-link-agent
The service is named com.mabl.link-agent.
# Check the service
sudo launchctl print system/com.mabl.link-agent
# Start or restart the service
sudo launchctl kickstart -k system/com.mabl.link-agent
On macOS, anything the service writes before the agent's own log starts goes to logs/service.out.log and logs/service.err.log in the install directory.
The Link Agent's own log is logs/agent.log in the install directory on both platforms.
The service restarts the Link Agent if it stops unexpectedly, and after the agent installs an update. It stays stopped when the agent exits on purpose, such as when mabl reports that its API key is no longer valid or its tunnels have been removed, so that it doesn't retry the same refusal. When you stop the service, the agent lets in-flight connections finish before it exits.
Change the configuration
To change tunnels or proxy settings later, edit the configuration file. The Link Agent applies the change while it runs, without a restart. See Link Agent configuration file.
You can also run the installer again and give different answers at the prompts, for example to add a tunnel or change the proxy.
Installing over an existing Link Agent is safe: the installer adds the new version beside the one that's there, the same way an update does, and leaves the configuration, logs, and other data in place.
Uninstall the Link Agent
The installer copies itself into the install directory, so you don't need the original archive to remove the agent:
sudo /opt/mabl/link-agent/install.sh --uninstall
The command removes the service and leaves the install directory, with your configuration and logs, in place. Add --purge to remove the install directory as well.
To stop mabl from routing tests to the tunnel, also see Removing mabl Link tunnels.