The default behaviour of Sputter should work fine for many use cases, but Sputter is designed to be super-configurable to adapt to whatever weird use case you can come up with.

Configuration

The Sputter server reads its configuration from a few different places, but we recommend using environment variables if you just want to tweak one or two things, or use a configuration file if you want to customize things in more detail.

Configuration File

The Sputter server will load configuration from either an appsettings.json or sputter.json file in the directory you run the server from, if they are present. These files must be valid JSON files but can include only the configuration parts you want to adjust, and the server will fall back to defaults for any configuration you don’t include.

Environment Variables

Any configuration option can be specified with either a configuration file or with environment variables. This can be particularly convenient when using the Docker container, especially if you’re only changing one or two options.

Drive Filters

When the server runs a measurement (either from a HTTP request or auto measurement), by default it will collect measurements for all available drives from all the enabled adapters. Sometimes, you might not want that, so Sputter supports filtering the discovered drives to only gather temperatures for some drives. Filters can be specified per-request (when using the HTTP API), but if you don’t specify one it will use any filters from the configuration file next.

Syntax

The syntax for filters is pretty simple: a wildcard match applied to the drive’s serial number and model number, optionally prefixed by an adapter name to limit matches to only drives found with that adapter. For example, if you provide a filter like "Z52*", Sputter will only gather measurements for drives where the serial number or model number starts with Z52. Similarly, if you provide a filter like dbus:ST8000VN004* will only include drives discovered from DBus where the serial or model number starts with ST8000VN004.

Filter Configuration

You can either provide filters with your request (over HTTP) or in the configuration file. When specified in the configuration file, the filter will be applied with any request that doesn’t specify a filter, or when running on a schedule.

  {
    "Sputter": {
        "Drives": [
            "dbus:ST8000VN004*",
            "*WD20EFRX*"
        ]
    }
}
  
  http://localhost:8080/measurements/WDC*
  
  http://localhost:8080/measurements/sysfs:*SN730*

Auto Measure Interval

You can set an interval (in seconds) and Sputter will automatically run that often, measuring any available drives (taking into account any filters). This is most useful if you have MQTT configured so you can regularly publish your drive temperatures over MQTT.

  {
    "Sputter": {
        "AutoMeasureInterval": 60
    }
}
  
  # bash
export SPUTTER__AUTOMEASUREINTERVAL=60

When this is enabled, the first measurement on server startup will be taken after 20% of the interval you have set (down to a minimum of 20s)

Allow Publishing All

By default, Sputter will not publish measurements on a schedule unless you either set a drive filter or set the AllowPublishingAll option in your configuration. This is to prevent possibly saturating your MQTT broker.

  {
    "Sputter": {
        "AllowPublishingAll": true
    }
}
  
  # bash
export SPUTTER__ALLOWPUBLISHINGALL="true"

MQTT

Sputter supports publishing drive measurements to an MQTT broker by adding your broker details to the configuration. Once your MQTT configuration is added, Sputter will automatically publish every measurement (either on-demand or scheduled) to MQTT. You can see more details on Sputter’s MQTT traffic in the MQTT Reference docs.

  {
    "MQTT": {
        "Server": "192.168.0.100",
        "UserName": "user",
        "Password": "password",
        "Port": 1338
    }
}
  
  # bash
export MQTT__SERVER="mqtt-server-name:1338"
export MQTT__USERNAME="user"
export MQTT__PASSWORD="password"

Scrutiny Support

You can add the API address of a Scrutiny server to gather measurements from a remote Scrutiny server (in addition to any local drives). Specify the full URL to the API address of your Scrutiny server:

  {
    "Scrutiny": {
        "ApiBaseAddress": "http://192.168.0.100:8080/api/"
    }
}

or

  {
    "Scrutiny": {
        "ApiBaseAddress": "https://scrutiny.domain.tld/api/"
    }
}

Set the Scrutiny__ApiBaseAddress to the full URL:

  # bash
export SCRUTINY__APIBASEADDRESS="http://192.168.0.100:8080/api/"
  
  # Docker
docker run -it --rm -p 8080:8080 -e SCRUTINY_APIBASEADDRESS="https://scrutiny.domain.tld/api/" quay.io/sputter/server:0.0.1

Once you’ve set this up, whenever Sputter gathers drive measurements it will also grab any available drives (and their temperatures) from your Scrutiny server. These will be included in the measurements along with any locally discovered drives.

Caching

By default, Sputter caches measurement results for a short time. This is mostly to prevent adding too much system load if requests stack up or anything like that. The default behaviour is to cache measurements for 120 seconds. You can adjust this to any interval (in seconds), or set it to 0 to disable measurement caching entirely.

  {
    "Caching": {
        "Lifetime": 60
    }
}
  
  # bash
export CACHING__LIFETIME=60

Example Configuration

Purely for reference sake, here is a (personally verified) example configuration of how I use Sputter running in Docker, managed with Compose, to feed my drive temperatures into Home Assistant:

Here is the sputter.json file with a basic configuration for Sputter, using auto-measurements and the MQTT integration and Home Assistant integration to measure a selection of drives every 60 seconds.

  {
    "Sputter": {
        "AutoMeasureInterval": 60,
        "Drives": [
            "dbus:*ST*",
            "dbus:*WD20EFRX*"
        ]
    },
    "MQTT": {
        "Server": "192.168.0.68",
        "UserName": "|REDACTED|",
        "Password": "|REDACTED|",
        "Port": 1883,
        "EnableHomeAssistant": true,
        "HomeAssistant": {
            "DeviceArea": "Office",
            "SingleDeviceMode": true,
            "ExpireAfter": 600
        }
    }
}

Obviously you would need to adapt your MQTT server details and drive filters to match your own environment.

Here is the Compose service definition I use to run Sputter on the host with the drives I want to monitor

  services:
  sputter:
    image: quay.io/sputter/server:0.0.1
    ports:
      - 8196:8080
    volumes:
      - ./sputter.json:/app/sputter.json # this is the configuration file for Sputter
      - /var/run/dbus:/var/run/dbus # bind mount the DBus socket to the container to measure drives