Skip to main content
Version: 2.0 (Preview)

Migrating from Automator 1.x

Run the Automator 2.0 setup script on each probe to migrate it from Automator 1.x. Automator 1.x does not update itself to 2.0.

What the Script Does​

The script migrates these parts of the installation:

  • the registration, with the client ID and the measurement history of the probe on the server
  • the configuration, which moves to ~/.surfmeter/config and is converted to the new format
  • the schedule, which the scheduling daemon runs instead of cron

Before changing the installation, the script creates ~/surfmeter-backup-<date>-<time>/ and prints its path. This directory contains an archive of ~/.surfmeter, the services, and the crontab. The script also moves the old installation into this directory.

The script moves existing log files, screen recordings, and reports to ~/.surfmeter and updates their output paths in the configuration. It lists every changed setting and moved file.

The old version keeps measuring until the new one runs. Only then does the script remove the old cron entries, while your other cron entries stay as they are. If the new version does not start, the script moves everything back, and the old version keeps measuring as before.

32-bit ARM cannot be migrated

Automator 2.0 does not support 32-bit ARM. On such a probe, the script stops before it changes anything, and the old version keeps measuring.

Running the Migration​

Download the new release from your Surfmeter Dashboard. Unpack it into ~/surfmeter, even if the old installation is located there, and run its setup.sh:

mkdir -p ~/surfmeter
tar -xf surfmeter-automator-2.0.0-linux-x86_64.tar.gz -C ~/surfmeter
sudo ~/surfmeter/setup.sh --dry-run    # optional: only show what would be done
sudo ~/surfmeter/setup.sh

The script finds the old installation through the paths in the crontab, or in the usual locations. If it finds more than one, choose one with --legacy-dir <directory>, the directory that contains config/ and profile/.

If a measurement of the old version is running, the script waits up to 15 minutes for it to finish. Use --wait-timeout to change this. See Setup for all options.

Where the Configuration Comes From​

This depends on how the old probe got its configuration:

  • If the old probe downloaded its configuration automatically, the new version gets it from your Surfmeter server.
  • If the configuration was edited on the probe, the script asks whether to keep it locally (the default) or use the server's configuration. If you keep the local configuration, configuration updates from the server are disabled.

You can decide up front with --config-source local or --config-source server.

When the configuration is to come from the server, the script first checks that the server has one for this probe. If it does not, the script keeps the local configuration and warns you. To switch to the server later:

  1. Import the configuration in the dashboard, publish it, and assign it to the client.
  2. Run surfmeter config update as the measurement user.

Settings that the new version no longer uses, such as the old download addresses and the extension updates, are dropped. The script lists them.

Changes You Need to Make​

Update any scripts or cron jobs that call surfmeter-automator, surfmeter-automator-gui, or surfmeter-automator-headless to use surfmeter. The old programs are no longer available.

Most old command names still work with a warning, but we recommend using the new ones. See the list of old command names. The commands loadSchedule and clearSchedule were removed, since the daemon replaces them, and clearLockfile is no longer needed.

Display and Environment Settings​

  • Instead of surfmeter-automator-gui, use --display $DISPLAY to run on an existing desktop session.
  • --headless is deprecated. Use --display browser-headless.
  • HEADLESS_RESOLUTION is replaced by SURFMETER_DISPLAY_RESOLUTION.
  • SURFMETER_DISABLE_XVFB and SURFMETER_XVFB_HEADLESS are no longer accepted. See Display Modes.
  • SURFMETER_CHROMEDRIVER_BINARY, --deeplinkLoadTimeout and --deeplinkWaitTimeout no longer have any effect.

Changes to the Schedule Config​

Automator converts these fields when it reads a local V1 file. It rejects V1 configurations downloaded from a server.

  • cronSchedule is now schedule.
  • cronLogFile is now logFile.
  • cmdSuffix, updates.extension, logNetworkRequests, and live were removed.
  • Unknown keys are now errors.

You can convert a local configuration by hand with surfmeter config migrate. See the Automator Config V2 reference for the new format.

Behavior Changes​

  • --flushDb now sends earlier results after the study instead of before it, and --flushDbTimeout is in seconds.
  • Screen recordings are .mp4 files, and are stored in ~/.surfmeter/recordings/ by default.
  • Packet captures are stored in ~/.surfmeter/pcaps/ by default.
  • The daemon skips runs missed during downtime. A probe that reboots at a fixed time every day therefore never runs a study scheduled within that window.

Migrating Docker Deployments​

The setup script does not migrate containers.

Docker migration creates a new client

The new image cannot reuse the old image's registration. It registers as a new client with an empty measurement history. The old client and its history remain on the server until AVEQ removes the client and frees its license.

To migrate:

  1. Stop the old container.
  2. Create a new Compose file according to Setup (Docker). The old mounts for profile, reports, and logs are replaced by one volume for ~/.surfmeter.
  3. Rename SURFMETER_AUTO_LOAD_SCHEDULE to SURFMETER_AUTO_START_DAEMON. The old name still works, with a warning.
  4. Start the new container.

Plan the switch so that the old and the new container do not measure at the same time.

If the Registration Cannot Be Carried Over​

The registration of the old version is stored in its browser profile. If the profile is gone or damaged, the probe cannot keep its client ID. The script then stops without changing anything, unless you pass --registration-key. In that case, it registers the probe as a new client and continues. The old client and its measurement history stay on the server, but get no new measurements. To disable the old client, use the client ID that the script prints.

If you get the error "The registration could not be carried over from the old version", nothing was removed, and the old version keeps measuring. Check the network connection and the proxy, and that no old measurement was running. Then, run the script again.

Do not register again to fix a migration error

Registering again creates a new client without the old client's measurement history. If migration keeps failing, send the log to AVEQ support.

Going Back to the Old Version​

The backup contains instructions. Show them with:

cat ~/surfmeter-backup-<date>-<time>/RESTORE.txt

To restore the old version, remove the daemon (surfmeter daemon uninstall as the measurement user) and the link /usr/local/bin/surfmeter, unpack surfmeter-backup.tar.gz from that directory to /, and restore the crontab from the backup.