storagebox-exporter

CLI tool that uploads the Hetzner Storage Box usage data from the Hetzner API to influxdb on a daily basis

Dependencies

• go
• influxdb v2+
• Optional:
  • make - for automatic installation support
  • docker
  • podman
  • systemd

Relevant documentation

• Hetzner API
• InfluxDB API
• Systemd Timers
• compose-scheduler

Installation

With Podman Quadlets and systemd timer

1. Configure storagebox_exporter.json (see the configuration section below).

2. Copy storagebox-exporter.container to $HOME/.config/containers/systemd/storagebox-exporter.container

3. Copy storagebox-exporter.timer to $HOME/.config/systemd/user/storagebox-exporter.timer

4. Reload the user's systemd daemon

    systemctl --user daemon-reload

5. Run it.

    systemctl --user start storagebox-exporter.timer

With Docker

docker-compose

1. Configure storagebox_exporter.json (see the configuration section below).

2. Run it.

   docker compose up --detach

docker build & run

1. Build the docker image.

   docker build . --tag storagebox-exporter

2. Configure storagebox_exporter.json (see the configuration section below).

3. Run it.

   docker run --rm --init --tty --interactive --read-only --cap-drop ALL --security-opt no-new-privileges:true --cpus 2 -m 64m --pids-limit 16 --volume ./storagebox_exporter.json:/app/storagebox_exporter.json:ro ghcr.io/rare-magma/storagebox-exporter:latest

With the Makefile

For convenience, you can install this exporter with the following command or follow the manual process described in the next paragraph.

make build
make install
$EDITOR $HOME/.config/storagebox_exporter.json

Manually

1. Build storagebox_exporter with:

   go build -ldflags="-s -w" -o storagebox_exporter main.go

2. Copy storagebox_exporter to $HOME/.local/bin/ and make it executable.

3. Copy storagebox_exporter.json to $HOME/.config/, configure it (see the configuration section below) and make it read only.

4. Copy the systemd unit and timer to $HOME/.config/systemd/user/:

   cp storagebox-exporter.* $HOME/.config/systemd/user/

5. and run the following command to activate the timer:

   systemctl --user enable --now storagebox-exporter.timer

It's possible to trigger the execution by running manually:

systemctl --user start storagebox-exporter.service

Config file

The config file has a few options:

{
 "InfluxDBHost": "influxdb.example.com",
 "InfluxDBApiToken": "ZXhhbXBsZXRva2VuZXhhcXdzZGFzZGptcW9kcXdvZGptcXdvZHF3b2RqbXF3ZHFhc2RhCg==",
 "Org": "home",
 "Bucket": "storagebox",
 "ApiToken": "ZXhhbXBsZXRva2VuZXhhcXdzZGFzZGptcW9kcXdvZGptcXdvZHF3b2RqbXF3ZHFhc"
}

• InfluxDBHost should be the FQDN of the influxdb server.
• Org should be the name of the influxdb organization that contains the energy consumption data bucket defined below.
• Bucket should be the name of the influxdb bucket that will hold the energy consumption data.
• InfluxDBApiToken should be the influxdb API token value.
  • This token should have write access to the BUCKET defined above.
• ApiToken should be the token used to access the hetzner api.
  • This can be configured in the Hetzner Console. Log in, choose a Project, go to Security → API Tokens and create a new read only token.

Troubleshooting

Check the systemd service logs and timer info with:

journalctl --user --unit storagebox-exporter.service
systemctl --user list-timers

Exported metrics

• size: Total space in bytes
• used: Used space in bytes
• used_data: Used space by data in bytes
• used_snapshot: Used space by snapshots in bytes

Exported metrics example

storagebox_stats,id=XXXX,name=box,type=bxxx,status=active,location=fsn1,samba=false,ssh=true,external_reachability=true,server=username.your-storagebox.de,host=FSN1-BXXXX,webdav=false,zfs=true size=5497558138880,used=3644984393728,used_data=2802055118848,used_snapshot=842929274880 1751132140

Example grafana dashboard

In storagebox-dashboard.json there is an example of the kind of dashboard that can be built with storagebox-exporter data:

Import it by doing the following:

1. Create a dashboard
2. Click the dashboard's settings button on the top right.
3. Go to JSON Model and then paste there the content of the storagebox-dashboard.json file.

Uninstallation

With the Makefile

For convenience, you can uninstall this exporter with the following command or follow the process described in the next paragraph.

make uninstall

Manually

Run the following command to deactivate the timer:

systemctl --user disable --now storagebox-exporter.timer

Delete the following files:

~/.local/bin/storagebox_exporter
~/.config/storagebox_exporter.json
~/.config/systemd/user/storagebox-exporter.timer
~/.config/systemd/user/storagebox-exporter.service

Credits

• podman quadlets
• reddec/compose-scheduler

This project takes inspiration from the following:

• fleaz/prometheus-storagebox-exporter