Skip to main content
Version: 2.0 (Preview)

Setup

This guide installs Automator directly on a Linux machine. For Docker, see Setup (Docker). If the machine already runs Automator 1.x, see Migrating from Automator 1.x.

Each release includes setup.sh. The script checks the machine and shows the planned changes before asking you to confirm. You can rerun it to complete any missing steps.

Installing Automator​

Open Clients > Create Client in your Surfmeter Dashboard, at https://surfmeter-server.<customer>-analytics.aveq.info/app/clients/new, where <customer> is your organization's name. The page fills in the installation commands for you:

  1. Select a registration key, and optionally enter a label and tags. If there is no key yet, create one under Registration Keys.
  2. Under Automator Version, select Surfmeter Automator v2.
  3. Under Available Software, select your platform, then download the archive with the button or the commands shown there. The commands also verify the checksum. The download link is valid for a few minutes, and the page renews it automatically.
  4. Copy and run the commands to unpack the archive, install Automator, and register the client.

The Clients > Software Downloads page (https://surfmeter-server.<customer>-analytics.aveq.info/app/clients/software) offers the same archives and steps, but does not fill in a registration key. Viewers have no access to the downloads. If you are a viewer, ask an editor or administrator of your organization.

To do the same by hand, you need the release archive, a registration key, and the address of your Surfmeter server.

There is one archive per architecture. Run uname -m to find out which one you need:

  • x86_64: surfmeter-automator-<version>-linux-x86_64.tar.gz
  • aarch64: surfmeter-automator-<version>-linux-arm64.tar.gz
Important: Install from the measurement user's account

Log in as the user that will run the measurements. Use sudo for the setup script, then run surfmeter commands as the measurement user. Automator refuses to run measurements as root.

Unpack the archive into ~/surfmeter and run the script:

mkdir -p ~/surfmeter
tar -xf surfmeter-automator-2.0.0-linux-x86_64.tar.gz -C ~/surfmeter
sudo ~/surfmeter/setup.sh

The script asks for your registration key and server address. You can also pass them directly:

sudo ~/surfmeter/setup.sh \
    --registration-key <registrationKey> \
    --server https://surfmeter-server.example.com \
    --label "Vienna office"

The script does not set tags. To set them, run surfmeter auth tags set <tags> afterwards.

Setup leaves the probe in this state:

  • Automator is installed in ~/surfmeter, and the command surfmeter works for every user.
  • The operating system packages, the browser, and the tools for the network studies are installed.
  • The probe is registered.
  • The scheduling daemon runs in the background.
Important: Assign a configuration to start measuring

The probe gets its configuration from your Surfmeter server. Assign a configuration to the new client, unless one is assigned automatically. The probe picks it up within 15 minutes.

Checking the Installation​

Run these commands as the measurement user:

surfmeter auth status --verify                # Is the probe registered and accepted by the server?
surfmeter daemon status                       # What is scheduled, and what is running?
surfmeter study list                          # Which studies does the configuration contain?
journalctl --user -u surfmeter-daemon -f      # Log of the daemon

If the script added the user to the pcap group for packet captures, log out and in again for this to apply to your own shell.

Setup Script Options​

  • --dry-run: show what was found and what would be done, without changing anything
  • -y, --yes, --unattended: do not ask, and use the defaults
  • --user NAME: the measurement user, if you do not run the script with sudo from that user's account
  • --archive FILE: install this release archive instead of the one the script was unpacked from
  • --registration-key KEY, --server URL, --label LABEL: registration of a new probe
  • --config-source local|server: where the configuration comes from after a migration
  • --legacy-dir DIR: the old installation, if there is more than one
  • --backup-dir DIR: create the backup directory somewhere else, for example on another disk
  • --wait-timeout SECONDS: how long to wait for running measurements of the old version (default: 900)
  • --install-dir DIR: install to an empty directory other than ~/surfmeter
  • --skip-deps, --skip-ffmpeg, --skip-browser, --skip-xvfb-service: leave out parts of the installation
  • --enable-gpu: give the user access to the GPU (amd64 only)
  • --proxy URL, --no-proxy LIST: proxy for the downloads of the installation
  • --allow-downgrade: install a release older than the installed one
  • --uninstall: remove Automator

Unattended Installation​

For remote or scripted installations, for example through Ansible, use --yes:

sudo ~/surfmeter/setup.sh --yes \
    --registration-key <registrationKey> \
    --server https://surfmeter-server.example.com

In this mode, the script:

  • keeps a local configuration that was edited on the probe
  • installs ffmpeg (--skip-ffmpeg leaves it out)
  • sets up the Xvfb display service
  • stops measurements of an old version that are still running after the waiting time
  • registers a new probe only if you pass --registration-key or set SURFMETER_DEFAULT_REGISTRATION_KEY

The exit code tells you the result:

  • 0: the probe is installed and measuring
  • 1: something failed, and the output says what
  • 3: the probe is installed but not registered yet

GPU Rendering (Optional)​

By default, the browser renders in software. On a Linux amd64 machine with a GPU, you can enable GPU rendering. The setup script can grant your user access to the GPU devices:

sudo ~/surfmeter/setup.sh --enable-gpu

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

The measurements must also start the browser with GPU support. Add the following options under Global Settings of your schedule config, or in the local automatorConfig.json:

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

To enable it only on certain probes, set SURFMETER_OPTIONS__ENABLE_GPU=1 in the environment instead.

GPU rendering changes the display behavior

Enabling the GPU switches the browser to offscreen rendering. The browser then no longer appears on the virtual display. This means that you cannot see it through VNC or in a screen recording. The measurements themselves are unaffected.

Behind a Proxy​

For the installation itself, pass the proxy to the script, since sudo does not pass on the proxy settings of your shell:

sudo ~/surfmeter/setup.sh --proxy http://proxy.example.com:3128

The daemon needs the proxy too. As the measurement user, run systemctl --user edit surfmeter-daemon.service and add the following:

[Service]
Environment=HTTP_PROXY=http://proxy.example.com:3128
Environment=HTTPS_PROXY=http://proxy.example.com:3128
Environment=NO_PROXY=localhost,127.0.0.1

Keep localhost and 127.0.0.1 in NO_PROXY. Then, restart the daemon:

systemctl --user restart surfmeter-daemon.service

A proxy limits what can be measured: network studies that use ICMP or UDP do not go through it, and browser studies measure the proxy as well.

If Something Goes Wrong​

The script stops at the first problem, reports the error and log file path, and suggests what to do next. Completed steps are kept. Fix the cause and run it again.

  • "The server does not accept the registration": check the network, proxy, and server address. The client may also have been deleted on the server. Ask AVEQ support before registering again.
  • "The scheduling daemon could not be installed" or "did not load a schedule": run journalctl --user -u surfmeter-daemon as the measurement user to see why. Usually, the configuration is not valid.

Uninstalling​

sudo ~/surfmeter/setup.sh --uninstall

This removes the scheduling daemon, the Xvfb display service, the command surfmeter, and the installation in ~/surfmeter. It asks before removing shared packages such as ffmpeg and Xvfb. With --yes, it removes Automator without asking, and keeps the shared packages.

The registration, configuration, and unsent measurements remain in ~/.surfmeter. To return the license, run surfmeter auth unregister before uninstalling. To remove everything, delete ~/.surfmeter afterwards.