shelly-exporter/docs/configuration.md

Configuration reference

Shelly Exporter reads one YAML file at startup. The default path is config.yaml; use the command-line flag to select another file:

./shelly-exporter -config /etc/shelly-exporter/config.yaml

Configuration is parsed strictly. Unknown fields, invalid value types, and duplicate YAML keys accepted by neither the parser nor validation cause startup to fail instead of being silently ignored.

Complete example

host: 0.0.0.0
port: 9090
logLevel: 4

shelly:
  timeoutSeconds: 10
  devices:
    - name: office-plug
      product: plug_s
      url: http://192.168.0.30
      username: admin
      password: secret

    - name: main-meter
      product: shelly_3em
      url: http://192.168.0.31
      username: admin
      password: another-secret

    - name: garage-relay
      product: shelly_1
      url: http://192.168.0.32
      username: ""
      password: ""

Top-level fields

Field	Required	Default	Description
host	yes	none	Literal IPv4 or IPv6 address on which the exporter listens. Hostnames such as localhost are not accepted. Use 0.0.0.0 to listen on all IPv4 interfaces.
port	yes	none	TCP listening port from 1 to 65535.
logLevel	no	0	Numeric Logrus severity described below.
shelly	yes	none	Shelly client and device configuration.

Log levels

Value	Level
0	Panic
1	Fatal
2	Error
3	Warn
4	Info
5	Debug
6	Trace

4 is a practical production default. Debug and trace logging can be useful during device communication troubleshooting.

Shelly fields

Field	Required	Default	Description
shelly.timeoutSeconds	no	10	Complete HTTP request timeout for each device. A value of 0 also selects the default; negative values are invalid.
shelly.devices	yes	none	Non-empty list of devices. Devices are contacted concurrently during a Prometheus scrape.

The timeout applies independently to each device. Since devices are scraped concurrently, one unavailable device delays the scrape by at most its own timeout rather than the sum of every device timeout.

Device fields

Field	Required	Description
name	yes	Unique stable device name. It becomes the device label on all metrics. Names are compared case-sensitively.
product	yes	Registered product identifier or gen1. Product normalization is described below.
url	yes	Absolute http:// or https:// base URL. The exporter appends /status. Queries and fragments are rejected.
username	no	HTTP Basic Authentication username.
password	no	HTTP Basic Authentication password.

Credentials are never used as metric labels. Keep the configuration file readable only by the exporter account because it contains plaintext passwords.

The exporter sends an Authorization: Basic header when either username or password is non-empty. In normal configurations, provide both values or leave both empty.

URL handling

Configured URL	Requested status URL
http://192.168.0.30	http://192.168.0.30/status
http://192.168.0.30/	http://192.168.0.30/status
https://shelly.example/device	https://shelly.example/device/status

For HTTPS device URLs, the exporter deliberately skips certificate verification. Self-signed, expired, and hostname-mismatched certificates are accepted without additional configuration.

Product identifiers

Family	Identifiers
Generic Gen1	gen1
Plugs	plug, plug_s
Relays and inputs	shelly_1, shelly_1pm, shelly_1l, shelly_2, shelly_2_5, shelly_4pro, shelly_uni, shelly_i3, shelly_button1
Energy meters	shelly_em, shelly_3em
Lights and dimmers	shelly_bulb, shelly_bulb_rgbw, shelly_duo, shelly_vintage, shelly_rgbw2, shelly_dimmer
Sensors and heating	shelly_ht, shelly_flood, shelly_smoke, shelly_door_window, shelly_motion, shelly_sense, shelly_gas, shelly_trv

Identifiers are converted to lowercase, and each punctuation or whitespace run becomes an underscore. Examples:

Input	Normalized identifier
plug-s	plug_s
Shelly 2.5	shelly_2_5
SHELLY 3EM	shelly_3em

Use gen1 for an unlisted product that returns a compatible Gen1 /status JSON response. The collector detects known optional response blocks and emits only corresponding metrics. A successful HTTP request does not guarantee that every model-specific field is understood; inspect /metrics and compare it with the raw device response.

Validation failures

The exporter refuses to start when:

• host is not a literal IP address;
• port is zero or outside the YAML target type range;
• logLevel is outside 0..6;
• the timeout is negative;
• the device list is empty;
• a device name is empty or duplicated;
• a product is empty or not registered;
• a URL is not absolute HTTP/HTTPS or contains a query or fragment;
• an unknown YAML field is present.

Configuration is loaded only during startup. Restart the process after editing the file.