RepoMirrors
/
ipmi_exporter
mirror of https://github.com/prometheus-community/ipmi_exporter
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Refactor and improve documentation 

* Streamline README
* Link to container imgages
* Move privileges part to separate doc
* Use absolute paths for `sudo` examples
* Emphasize `sudo` only being needed for local metrics
This commit is contained in:
Conrad Hoffmann 2024-10-18 10:03:21 +02:00
parent b08f887d6b
commit 557f2c072b
6 changed files with 99 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -31,6 +31,12 @@ For Kubernets, you can use the community-maintained [Helm chart][helm].
[helm]: https://github.com/prometheus-community/helm-charts/tree/main/charts/prometheus-ipmi-exporter "IPMI exporter Helm chart in the helm-charts Github repo"
Pre-built container images are available on [dockerhub][dockerhub] and
[quay.io][quay.io].
[dockerhub]: https://hub.docker.com/r/prometheuscommunity/ipmi-exporter
[quay.io]: https://quay.io/repository/prometheuscommunity/ipmi-exporter
### Building from source
You need a Go development environment. Then, simply run `make` to build the
@ -43,23 +49,16 @@ This uses the common prometheus tooling to build and run some tests.
Alternatively, you can use the standard Go tooling, which will install the
executable in `$GOPATH/bin`:
go get github.com/prometheus-community/ipmi_exporter
go install github.com/prometheus-community/ipmi_exporter@latest
### Building a Docker container
### Building a container image
You can build a Docker container with the included `docker` make target:
You can build a container image with the included `docker` make target:
make promu
promu crossbuild -p linux/amd64 -p linux/arm64
make docker
This will not even require Go tooling on the host. See the included [docker
compose example](docker-compose.yml) for how to use the resulting container.
### Building a RPM Package
See [how to build a RPM package](contrib/rpm/README.md).
## Running
A minimal invocation looks like this:
@ -86,44 +85,12 @@ installed:
- `ipmi-sel`
- `ipmi-chassis`
### Running as unprivileged user
When running a container image, make sure to:
If you are running the exporter as unprivileged user, but need to execute the
FreeIPMI tools as root, you can do the following:
- set `config.file` to where the config file is mounted
- expose the default port (9290) or set `web.listen-address` accordingly
1. Add sudoers files to permit the following commands
```
ipmi-exporter ALL = NOPASSWD: /usr/sbin/ipmimonitoring,\
/usr/sbin/ipmi-sensors,\
/usr/sbin/ipmi-dcmi,\
/usr/sbin/ipmi-raw,\
/usr/sbin/bmc-info,\
/usr/sbin/ipmi-chassis,\
/usr/sbin/ipmi-sel
```
2. In your module config, override the collector command with `sudo` for
every collector you are using and add the actual command as custom
argument. Example for the "ipmi" collector:
```yaml
collector_cmd:
ipmi: sudo
custom_args:
ipmi:
- "ipmimonitoring"
```
See the last module in the [example config](ipmi_remote.yml).
### Running in Docker
**NOTE:** you should only use Docker for remote metrics.
See [Building a Docker container](#building-a-docker-container) and the example
`docker-compose.yml`. Edit the `ipmi_remote.yml` file to configure IPMI
credentials, then run with:
sudo docker-compose up -d
By default, the server will bind on `0.0.0.0:9290`.
**NOTE:** you should only use containers for collecting remote metrics.
## Configuration
@ -145,3 +112,9 @@ using the `--web.config.file` parameter. The format of the file is described
For a description of the metrics that this exporter provides, see the
[metrics](docs/metrics.md) document.
## Privileges
Collecting host-local IPMI metrics requires root privileges. See
[privileges](docs/privileges.md) document for how to avoid running the exporter
as root.

25
docs/configuration.md
View File

@ -1,17 +1,20 @@
# Configuration
Simply scraping the standard `/metrics` endpoint will make the exporter emit
local IPMI metrics. No special configuration is required.
local IPMI metrics. If the exporter is running with sufficient privileges, no
special configuration is required. See the [privileges document](privileges.md)
for more details.
For remote metrics, the general configuration pattern is similar to that of the
[blackbox exporter](https://github.com/prometheus/blackbox_exporter), i.e.
Prometheus scrapes a small number (possibly one) of IPMI exporters with a
`target` and `module` URL parameter to tell the exporter which IPMI device it
should use to retrieve the IPMI metrics. We offer this approach as IPMI devices
often provide useful information even while the supervised host is turned off.
If you are running the exporter on a separate host anyway, it makes more sense
to have only a few of them, each probing many (possibly thousands of) IPMI
devices, rather than one exporter per IPMI device.
For remote metrics, the general configuration pattern is that of a
[multi-target exporter][multi-target]. Please read that guide to get the general
idea about this approach.
[multi-target]: https://prometheus.io/docs/guides/multi-target-exporter/ "Understanding and using the multi-target exporter pattern - Prometheus docs"
We offer this approach as IPMI devices often provide useful information even
while the supervised host is turned off. Also, you can have a single exporter
instance probing many (possibly thousands of) IPMI devices, rather than one
exporter per IPMI device.
**NOTE:** If you are using remote metrics, but still want to get the local
process metrics from the instance, you must use a `default` module with an
@ -83,7 +86,7 @@ Create a YAML file that contains a list of targets, e.g.:
job: ipmi_exporter
```
This file needs to be stored on the Prometheus server host. Assuming that this
This file needs to be stored on the Prometheus server host. Assuming that this
file is called `/srv/ipmi_exporter/targets.yml`, and the IPMI exporter is
running on a host that has the DNS name `ipmi-exporter.internal.example.com`,
add the following to your Prometheus config:

31
docs/privileges.md Normal file
View File

@ -0,0 +1,31 @@
# Privileges
If you are running the exporter as unprivileged user, but need to execute the
FreeIPMI tools as root (as is likely necessary to access the local IPMI
interface), you can do the following:
**NOTE:** Make sure to adapt all absolute paths to match your distro!
1. Add sudoers files to permit the following commands
```
ipmi-exporter ALL = NOPASSWD: /usr/sbin/ipmimonitoring,\
/usr/sbin/ipmi-sensors,\
/usr/sbin/ipmi-dcmi,\
/usr/sbin/ipmi-raw,\
/usr/sbin/bmc-info,\
/usr/sbin/ipmi-chassis,\
/usr/sbin/ipmi-sel
```
2. In your module config, override the collector command with `sudo` for
every collector you are using and add the actual command as custom
argument. Example for the "ipmi" collector:
```yaml
collector_cmd:
ipmi: /usr/bin/sudo
custom_args:
ipmi:
- "/usr/sbin/ipmimonitoring"
```
See also the [sudo example config](../ipmi_local_sudo.yml).
Note that no elevated privileges are necessary for getting remote metrics.

4
ipmi_local.yml
View File

@ -1,7 +1,9 @@
# Configuration file for ipmi_exporter
# This is an example config for scraping the local host.
# In most cases, this should work without using a config file at all.
# In most cases, this should work without using a config file at all, but here
# are some examples of things that can be customized. If you require privilege
# elevation to get the local metrics, see the `ipmi_local_sudo.yml` example.
modules:
default:
# Available collectors are bmc, bmc-watchdog, ipmi, chassis, dcmi, sel, sel-events and sm-lan-mode

32
ipmi_local_sudo.yml Normal file
View File

@ -0,0 +1,32 @@
# Configuration file for ipmi_exporter
# This is an example config for scraping the local host, using `sudo` to
# elevate privileges for access to the IPMI interface.
modules:
default:
# Available collectors are bmc, bmc-watchdog, ipmi, chassis, dcmi, sel, sel-events and sm-lan-mode
collectors:
- ipmi
- sel
# Got any sensors you don't care about? Add them here.
exclude_sensor_ids:
- 2
- 29
- 32
# Define custom metrics for SEL entries
sel_events:
- name: correctable_memory_error
regex: Correctable memory error.*
# USING ANY OF THE BELOW VOIDS YOUR WARRANTY! YOU MAY GET BITTEN BY SHARKS!
# You can override the command to be executed for a collector. Paired with
# custom_args, this can be used to e.g. execute the IPMI tools with sudo.
# Must be added for every enabled collector. Adapt the path to match your
# distro, and read `docs/privileges.md`!
collector_cmd:
ipmi: /usr/bin/sudo
sel: /usr/bin/sudo
custom_args:
ipmi:
- "/usr/sbin/ipmimonitoring"
sel:
- "/usr/sbin/ipmi-sel"

21
ipmi_remote.yml
View File

@ -4,7 +4,6 @@
# Information required to access remote IPMI interfaces can be supplied in the
# 'modules' section. A scrape can request the usage of a given config by
# setting the `module` URL parameter.
modules:
default:
# These settings are used if no module is specified, the
@ -66,23 +65,3 @@ modules:
custom_args:
ipmi:
- "--bridge-sensors"
advanced:
# Use these settings when scraped with module=advanced.
user: "some_user"
pass: "secret_pw"
privilege: "admin"
driver: "LAN"
collectors:
- ipmi
- sel
# USING ANY OF THE BELOW VOIDS YOUR WARRANTY! YOU MAY GET BITTEN BY SHARKS!
# You can override the command to be executed for a collector. Paired with
# custom_args, this can be used to e.g. execute the IPMI tools with sudo:
collector_cmd:
ipmi: sudo
sel: sudo
custom_args:
ipmi:
- "ipmimonitoring"
sel:
- "ipmi-sel"