Local Configuration

We recommend managing the configuration in the dashboard. You can also configure a probe locally, for example for a quick test or on a network without access to the server.

The configuration is stored in ~/.surfmeter/config/, and consists of the publicConfig.json and automatorConfig.json files. To use a different directory, pass --configDir to a command.

Editing the Configuration

Use these commands instead of editing files directly, because they validate your changes:

surfmeter config edit measurements                   # Edit publicConfig.json in your editor
surfmeter config edit schedule                       # Edit automatorConfig.json in your editor
surfmeter config set measurements my-config.json     # Replace publicConfig.json with a file
surfmeter config set schedule my-schedule.json       # Replace automatorConfig.json with a file
cat my-schedule.json | surfmeter config set schedule - # Read the file from standard input

Server updates overwrite local edits

These commands refuse to run while the probe gets configuration updates from the server. --force allows the edit, but the next update can still overwrite it. To keep your changes, turn off server updates or use local overrides.

The daemon applies a changed schedule automatically after config set or config edit. If you edit the files by hand, run surfmeter daemon reload.

Turning Off Updates from the Server

To stop a probe from downloading its configuration, set an empty schedule in automatorConfig.json:

{
  "version": 2,
  "updates": {
    "config": {
      "schedule": ""
    }
  }
}

Alternatively, set the environment variable SURFMETER_DISABLE_CONFIG_UPDATE=1 for the daemon.

Using Your Own Update Server

A probe can download its configuration from another server, a Git repository, or a local file:

{
  "version": 2,
  "updates": {
    "config": {
      "schedule": "0 * * * *",
      "url": "https://config.example.com/surfmeter-config.tar.gz"
    }
  },
  "globalUpdateSettings": {
    "auth": {
      "username": "user",
      "password": "secret"
    }
  }
}

The URL can be an http(s) URL to a file or a Git repository (ending in .git), or a file:// URL. See the reference for all options. A downloaded configuration must be in the V2 format.

Local Overrides

You can add settings on a single probe without changing the configuration it gets from the server. Automator reads two additional files from the configuration directory, which are never overwritten by updates:

• publicConfig.local.json: Studies are merged with those of publicConfig.json by their ID, and the local version takes priority. This lets you add a study, or change one.
• automatorConfig.local.json: Settings are merged with automatorConfig.json.

A local schedule list replaces the full schedule

If automatorConfig.local.json contains studySchedules, that list replaces all entries from automatorConfig.json. It does not add to the server's schedule.

You can edit them with --local:

surfmeter config edit measurements --local
surfmeter config set schedule my-overrides.json --local

Both files can be in JSON5 format, which allows comments and trailing commas. For example, this adds a study:

publicConfig.local.json

{
  "version": 1,
  "studies": [
    {
      "id": "STUDY_DNS_LOCAL",
      "type": "NETWORK",
      "subject": "dns",
      "params": {
        "host": ["example.com"]
      }
    }
  ]
}

Note

Running ad-hoc studies with surfmeter measure or --url writes the generated study to publicConfig.local.json.

Migrating a Local Version 1 File

Automator converts a local V1 automatorConfig.json when it reads the file. It rejects V1 files downloaded from a server. To save your configuration in the new format, run surfmeter config migrate.