rrdsrv
An RRDtool api server that exports a subset of rrdtool commands over http(s).
Be sure to checkout the grafana plugin.
Demo video.
Usage
Usage of ./rrdsrv:
-config string
Path to configuration file
Configuration
See examples/defaults.cfg for all configuration options.
API
/api/v1/ping
Returns the json encoded string "pong"
Runs the equivalent to:
$ rrdtool xport $opts -- $xport
with the following exceptions:
- Short options are disabled.
- A new format=json|xml option replaces the --json.
- json output is the default.
/api/v1/graph?graph=$graph[&...$opts]
Runs the equivalent to:
$ rrdtool xport $opts -- $graph
with the following exceptions:
- Short options are disabled.
- SVG output is the default.
- Only PNG and SVG is supported in the imgformat option.
/api/v1/list_metrics?[glob=$glob]
Runs the configured list_rrds_command then extracts
matching ds metrics from the returned rrds.
The $path:$ds pairs are then matched against the provided glob pattern.
Signed query and post params
To allow users to view signed graphs, without arbitrary rrd access,
you can give them a signed query with an optional unix time for expiry.
Example signed and encrypted graph request:
https://$server/api/v1/graph?foo=bar&x=$expiry&s=$sig
If signed_query_secret
or signed_query_secret_file
is set in the rrdsrv configuration file, then only signed or password authenticated queries are permitted.
A signed query is computed as:
path=/api/v1/ping,...
sig=hmac-sha256($secret, $path || "?" || $query-params || "&")
signed=$path || "?" || $query-params || "&s=$sig"
For testing you can generate a signed query string via:
$ rrdsrv -c your-config.cfg -sign-query "$path?$query"
Notes on security
rrdsrv provides a few mechanisms for secure access:
- We recommend you setup a security sandbox for any public access to the api server.
See example/jail.cfg for one example of how to do this.
- We strongly recommend you do not allow public access to rrdsrv except via presigned queries.
- For simple setups you can use http basic authentication, see example/basic-auth.cfg
Building
$ go build
$ ./rrdsrv --help