Setup¶

How you set up Automator depends on your needs. You can either run it natively (if you use one of the supported operating systems) or in a Docker container. The following section is for the native installation; read the Docker Setup guide for Docker.

Tip

AVEQ also provides Ansible scripts for installing Automator on remote-managed devices. Ask us!

OS/User Requirements¶

You need an operating system that fulfills the requirements mentioned in the previous section.

Some further requirements are:

Certain dependencies may need sudo permissions in order to be installed (e.g. packages via apt or dnf). So you need a sudo user on your machine, at least for the installation process. To add your user to the appropriate group:
```
# Debian/Ubuntu:
sudo usermod -aG sudo $USER
# RHEL/AlmaLinux/Rocky/Fedora:
sudo usermod -aG wheel $USER
```
You need to log out and log in again for the changes to take effect.
The Surfmeter Automator tool itself can and should run on a non-privileged user account. For the measurements themselves, no sudo access is needed, except for clearing DNS caches. In other words, please do not run Surfmeter as root.
The OS must be connected to the Internet to register the software, perform measurements, and apply updates.
You must not use any proxy. For details see the Proxy section below.
The path in which Automator is installed must not use any spaces.

Tip

Automator works on CLI-only systems via a headless mode (see Headless vs. GUI). You do not need a GUI or a display connected to the device. If you do want to use the GUI, you can do that, but it might interfere with your display while it's running.

For the installation, you can pick any location, but we recommend placing Surfmeter into a dedicated folder in the home folder of the user that will run the software. For instance, to create a folder surfmeter in the home folder, you can use the following commands:

BashWindows Batch (cmd)PowerShell

cd ~
mkdir -p surfmeter

cd %USERPROFILE%
mkdir surfmeter

cd ~
mkdir surfmeter

Installation Files (Automated Download)¶

AVEQ will send you a list of download commands together with your credentials. They download and extract the three required components (the browser extension, the Automator, and your configuration) into the ~/surfmeter folder you created above.

The commands look like the following. Replace each wget line with the exact one AVEQ sent you (it contains your customer name, download password, and server address); the mkdir, unzip, and tar lines can be run as-is.

cd ~/surfmeter

# Download and extract the browser extension (Surfmeter Lab):
wget -O extension-latest.zip --http-user CUSTOMER --http-password PASSWORD 'https://download-server.YOUR-SERVER/download/surfmeter-lab/latest?customer=CUSTOMER'
mkdir -p surfmeter-lab
unzip -o extension-latest.zip -d surfmeter-lab

# Download and extract the Automator:
wget -O automator-latest.tar.bz2 --http-user CUSTOMER --http-password PASSWORD 'https://download-server.YOUR-SERVER/download/surfmeter-lab-automator/latest?customer=CUSTOMER'
mkdir -p surfmeter-lab-automator
tar -xvf automator-latest.tar.bz2 -C surfmeter-lab-automator

# Download and extract the configuration:
wget -O config-latest.tar.bz2 --http-user CUSTOMER --http-password PASSWORD 'https://download-server.YOUR-SERVER/download/surfmeter-lab-automator-config/latest?customer=CUSTOMER'
mkdir -p config
tar -xvf config-latest.tar.bz2 -C config

After download and extraction of all three files, the file layout should be as follows:

~/surfmeter
    ├── config
    │   ├── automatorConfig.json           # the Automator configuration incl. measurement schedule
    │   ├── publicConfig.json              # the measurement configuration (optional)
    │   └── cloudLogging.json              # Google Cloud Log configuration (optional)
    ├── surfmeter-lab
    │   ├── app.html
    │   ├── assets
    │   ├── css
    │   ├── js
    │   ├── manifest.json
    │   ├── options.html
    │   ├── player.html
    │   └── popup.html
    └── surfmeter-lab-automator
        ├── setup.sh
        ├── install_chrome_for_testing.sh     # Installs the pinned Chrome for Testing (amd64)
        ├── .chrome_version                   # The pinned Chrome for Testing version
        ├── run_vnc_server.sh
        ├── download_crx.sh
        ├── README.md
        ├── LICENSES.md
        ├── surfmeter-automator.cjs            # The main executable
        ├── surfmeter-automator-0.13.2.tar.bz2 # The original downloaded archive
        ├── surfmeter-automator-gui            # The GUI wrapper
        └── surfmeter-automator-headless       # The headless wrapper

Setup Script¶

Now, navigate to the folder wher you extracted the Automator files and run the setup script:

cd ~/surfmeter/surfmeter-lab-automator
sudo ./setup.sh

This will run the installation script, installing all necessary third-party dependencies. It may take a while.

The script supports:

Debian-based systems (Debian 10+, Ubuntu 20.04+, Raspbian)
RHEL-family systems (AlmaLinux 8+, Rocky Linux 8+, CentOS 8+, RHEL 8+, Fedora 36+)

On Debian-based systems it uses apt, on RHEL-family systems it uses dnf (with EPEL and RPM Fusion as needed).

Which browser gets installed?

On amd64 the script installs Chrome for Testing, pinned to the version in the bundled .chrome_version file, via install_chrome_for_testing.sh. Chrome for Testing keeps the automation flags we need (regular Chrome removed extension loading in v142+) and bundles the Widevine CDM, so DRM-protected content plays with no extra step. It is installed into your home folder (~/.local/share/chrome-for-testing), and SURFMETER_CHROME_BINARY, SURFMETER_CHROMEDRIVER_BINARY, and CHROME_PATH are written to your ~/.profile.

On ARM (including the Raspberry Pi), where there is no Chrome for Testing build, the script installs the distribution's Chromium and ChromeDriver instead.

Warning

If you are under macOS or Windows, please install the dependencies manually as shown below.

To ensure that you can run the software without issues, please test the following command:

cd ~/surfmeter/surfmeter-lab-automator
node ./surfmeter-automator.cjs --help

This should output some usage notes. You're done!

GPU Rendering (Optional)¶

By default, the browser renders in software. On a Linux amd64 machine that has a GPU, you can let the browser render on the real hardware instead. This is opt-in.

The graphics drivers are installed as normal system packages, so the only extra step is granting your user access to the GPU devices. The setup script can do this for you:

sudo ./setup.sh --enable-gpu

Log out and back in afterwards so the new group membership takes effect.

Granting device access is not enough on its own — the measurements must also launch the browser with GPU support. Set this once in automatorConfig.json under globalScheduleSettings.options, and every scheduled study inherits it. For more info, see the configuration reference.

{
  "globalScheduleSettings": {
    "options": {
      "enableGpu": true,
      "chromeArgs": [
        "ozone-platform=headless",
        "use-gl=angle",
        "use-angle=vulkan",
        "enable-features=Vulkan",
        "ignore-gpu-blocklist"
      ]
    }
  }
}

GPU rendering changes the display behavior

Enabling the GPU switches the browser to offscreen rendering (via the ozone-platform=headless flag above). As a result, the browser no longer appears on the Xvfb display. The measurements themselves are unaffected.

Manual Installation¶

Follow the below steps to manually install the software.

General Software Requirements¶

Surfmeter Automator requires the some additional software on your operating system. You should install this software manually according to the instructions of the respective software.

Tip

If you run Linux (Debian/Ubuntu, RHEL-family, or Raspbian), you can also skip this section and use our setup.sh installation script to install the software automatically. Just follow that guide and you're all set. Read on if you want to manually install the software or run Surfmeter Automator on macOS or Windows.

We need the following command line software:

curl
unzip
tar with bzip2 support
jq

Ensure your system has these commands installed via:

Debian/Ubuntu/RaspbianRHEL/AlmaLinux/Rocky/FedoramacOSWindows

sudo apt install curl unzip tar bzip2 jq

sudo dnf install curl unzip tar bzip2 jq

We recommend using Homebrew to install the software. If you don't have Homebrew installed, you can install it with the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then, install the software with the following commands:

brew install jq

We recommend using WSL (Windows Subsystem for Linux) to install the software. If you don't have WSL installed, you can install it with the following command:

wsl --install

Then, install the software with the following commands:

sudo apt install curl unzip tar bzip2 jq

Node.js¶

We tested Automator with Node v20 LTS. Node v18 still works, but it is recommended to use Node v20 LTS or higher.

To install Node.js, see the Node.js website. You may choose to use a package manager or install the software manually via its installer, depending on your needs.

Xvfb¶

This only works under Linux. We need Xvfb for running a headless display.

Install the Xvfb and X11 utility packages:

Debian/Ubuntu/RaspbianRHEL/AlmaLinux/Rocky/CentOSFedora

sudo apt install xvfb x11-utils x11-xserver-utils

sudo dnf install xorg-x11-server-Xvfb xorg-x11-utils xorg-x11-server-utils

sudo dnf install xorg-x11-server-Xvfb xdpyinfo xset xrandr

Browser and WebDriver¶

You need a compatible browser and matching WebDriver. On Linux, the setup.sh script installs the right one for you — Chrome for Testing on amd64, distribution Chromium on ARM — so you only need this section if you are installing manually (for example on macOS) or want to understand what gets installed.

We support:

Chrome for Testing with matching ChromeDriver — the default on amd64. It is a versioned, non-auto-updating build that keeps the --load-extension automation flag (removed from regular Chrome in v142+) and bundles the Widevine CDM, so DRM-protected content plays with no extra step.
Chromium with ChromeDriver — the fallback on ARM, where there is no Chrome for Testing build.

Chrome for Testing (recommended)¶

The Automator ships an install script next to it that downloads Chrome for Testing and the matching ChromeDriver:

cd ~/surfmeter/surfmeter-lab-automator
sudo ./install_chrome_for_testing.sh

It installs into ~/.local/share/chrome-for-testing, with launchers in ~/.local/bin. When you run the full setup.sh, this step is done for you against the pinned .chrome_version, and the SURFMETER_CHROME_BINARY, SURFMETER_CHROMEDRIVER_BINARY, and CHROME_PATH environment variables are written to your ~/.profile.

Don't use regular Chrome

Regular Chrome (stable/beta/dev) removed extension loading support in v142+. Only Chrome for Testing keeps the automation flags we require.

Chromium (ARM / alternative)¶

To install the distribution's Chromium and ChromeDriver:

Debian/Ubuntu/RaspbianRHEL/AlmaLinux/Rocky/CentOS/Fedora

sudo apt install chromium chromium-driver

Chromium and ChromeDriver are available from EPEL (EL) or the default repos (Fedora):

sudo dnf install chromium chromedriver

Specifying binary paths manually¶

If your browser and driver live in a non-standard location, point Automator at them explicitly:

surfmeter-automator --chromeBinary=/path/to/chrome --chromeDriverBinary=/path/to/chromedriver checkRegistration

Or set them in your automatorConfig.json:

{
    "globalScheduleSettings": {
        "options": {
            "chromeBinary": "/path/to/chrome",
            "chromeDriverBinary": "/path/to/chromedriver"
        }
    }
}

Optional Additional Software¶

Surfmeter Automator may use the following third-party software if available. These are already included in the Docker image.

Google Lighthouse Node.js package
Ookla Speedtest CLI

Uninstalling¶

If you installed the dependencies with setup.sh, the same script can remove them again. Run it with --uninstall:

cd ~/surfmeter/surfmeter-lab-automator
sudo ./setup.sh --uninstall

This reverses what the script set up: it removes Chrome for Testing (from ~/.local) and its ~/.profile environment block, the global npm packages (Lighthouse and the log formatters), and the Xvfb user service, and then asks before removing shared system packages (ffmpeg, Node.js, the distribution Chromium, Xvfb). Add --unattended to skip the prompts. Anything installed manually is left alone.

Then remove the Automator files and its state directory:

rm -rf ~/surfmeter ~/.surfmeter

If you set things up manually instead of with setup.sh, remove the pieces yourself. Stop and delete the Xvfb service, if you created it:

systemctl --user stop xvfb-surfmeter.service
rm -f $HOME/.config/systemd/user/xvfb-surfmeter.service
systemctl --user daemon-reload

Optionally remove the additional software you installed, such as ffmpeg, Node.js, Chromium/ChromeDriver, and Xvfb. Chrome for Testing (if you used it) lives under ~/.local/share/chrome-for-testing and ~/.local/bin; the packages below only apply if you installed the distribution's Chromium.

Debian/UbuntuRHEL/AlmaLinux/Rocky/CentOS/Fedora

sudo apt remove ffmpeg nodejs chromium chromium-driver xvfb

sudo dnf remove ffmpeg nodejs chromium chromedriver xorg-x11-server-Xvfb

We'll cover basic usage in the following section.

Proxy¶

Some environments require all traffic to go through a system-wide proxy. Surfmeter Automator can run behind an HTTP/HTTPS proxy, but it will not work fully: an HTTP proxy can only carry HTTP(S) traffic, so several measurement types are degraded or unavailable. We therefore discourage using a proxy unless your environment leaves no alternative.

To run behind a proxy, set the following environment variables in the shell that launches the software:

export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port
export NO_PROXY=localhost,127.0.0.1

Also set those variables in the user's crontab, by running crontab -e and adding the above lines at the top.

Keep localhost and 127.0.0.1 in NO_PROXY: the automator's local connections to the browser (WebDriver and DevTools) must stay direct. The proxy itself must be able to reach both the Surfmeter server and the measurement target hosts.

With these variables set, the following traffic is routed through the proxy:

The automator's communication with the Surfmeter server (registration, configuration, and result upload)
All browser-based Web and Video measurements

Note

Routing the automator's own communication with the Surfmeter server through the proxy requires version 1.54.0 or newer. With earlier versions, only the browser-based measurements respect the proxy.

Warning

Even with the above settings, expect the following limitations:

You will generally be measuring the performance of the proxy rather than the actual Internet connection.
Web and Video measurements fall back to TCP instead of QUIC/HTTP-3.
Conferencing measurements degrade or fail, because their WebRTC media uses UDP that an HTTP proxy cannot carry.
Native command-line measurements (ICMP ping, traceroute, DNS, Ookla speedtest, TLSmeter, HTTP prober) use ICMP, UDP, or raw TCP that the proxy cannot carry. They run directly and will fail where direct egress is blocked.
If the proxy requires authentication, browser measurements will fail, because Chrome does not accept credentials embedded in the proxy URL.